Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

docs: teach the 0.3 author model

kashorin3c9e635d013c
diff --git a/docs/guide/packages.md b/docs/guide/packages.md
index fcc5233f..802cf626 100644
--- a/docs/guide/packages.md
+++ b/docs/guide/packages.md
@@ -24,7 +24,7 @@ the final composition. Both participate in the same graph, with explicit inputs
## Components follow the work
-A video's spatial structure is organized where that organization is useful. Media Track can present
+A video's spatial structure is organized where that organization is useful. Visual Track can present
an ordinary clip or picture; a project component can coordinate a moving video viewport, labels and
a diagram inside one scene. Independent captions or overlays can remain separate contributions.
Each component owns the content whose behavior belongs together.
diff --git a/docs/guide/studio-temporal-windows.md b/docs/guide/studio-temporal-windows.md
index e11a1d92..e8ea8b00 100644
--- a/docs/guide/studio-temporal-windows.md
+++ b/docs/guide/studio-temporal-windows.md
@@ -1,69 +1,51 @@
---
title: Timing edits in Studio
-description: Choose what follows speech, what uses the clock, and what a timing edit changes.
+description: Edit the declaration that produced an absolute Instant or Window.
---
-A timing expression records an authoring decision. An explanation can follow a spoken phrase;
-a flash can follow its answer; an independently paced animation can use the film clock. Studio
-edits the decision expressed by that form.
+Components use absolute Instants and Windows. Studio follows the graph to the value's producer and
+edits that declaration; it does not ask every visual, audio, caption or text component to understand
+the source domain.
-[Script](../quickstart/script.md) gives phrases and events their Selection and Moment identities.
-The Timeline places the prepared performances; components use those identities or clock positions
-to receive an Instant or Window. A silent animation uses the same Timeline with an authored extent.
-
-## Choose the relationship to edit
+## Absolute declarations
| Author form | Moving it changes | Trimming it changes |
| --- | --- | --- |
-| `during={story.selection.proof}` | Both shared Script anchors by the same number of semantic stops; duration may change | The chosen Selection boundary |
-| `at={story.moment.reveal}` for an event | The shared Moment anchor | No duration is declared |
-| `at={story.selection.proof} boundary="start"` for an event | Only the Selection's start anchor | No duration is declared |
-| `at={story.moment.reveal} for="8f"` | The Moment; duration stays eight frames | The trailing duration; the Moment stays fixed |
-| `until={story.moment.reveal} for="8f"` | The Moment; duration stays eight frames | The leading duration; the Moment stays fixed |
-| `at="2s" for="8f"` | The authored clock position | The trailing duration |
-| `instant="moment.cue + 2f" moment={story.moment.reveal}` | The local offset; the Moment stays fixed | No duration is declared |
-| `start="…" end="…"` | Both endpoint expressions by the same frame delta | Only the chosen endpoint expression |
-| `during={story.segment.opening}` or `during="program"` | Follows the structural span; no timeline drag | No timeline trim |
-
-The consuming Surface decides whether it needs an Instant or a Window and which forms it exposes.
-For an event bound to a Selection's end, use `boundary="end"` with the same boundary-only behavior.
-
-## Keep shared meaning and local offsets distinct
-
-Moving `at={story.moment.reveal}` relocates the Moment in Script. Every consumer of that Moment
-then follows the changed relationship. Moving `instant="moment.cue"` with the same bound Moment
-instead changes a local offset, initially zero. It leaves the shared Script event in place.
+| `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 |
-Use `instant="moment.cue + 2f"` with `moment={story.moment.reveal}` for a deliberate lead or lag.
-Arithmetic does not go inside a graph reference such as `{story.moment.reveal}`.
+An Instant reference behaves the same way: `at={claim}` follows the declaration that produced
+`claim`; `at="2s"` edits its own clock literal.
-An event and its duration are independent choices. `at/for` offers a duration handle on the trailing
-edge; `until/for` offers it on the leading edge. There is no opposite trim handle that secretly moves
-a shared event and compensates by changing its duration.
+## Domain-produced values
-## Preserve the chosen words and boundaries
+Narrative time is projected before it reaches the component:
-Word starts, word ends and structural boundaries are distinct semantic anchors. A pause can belong
-to the preceding or following phrase. Dragging uses semantic stops at distinct frame positions;
-where supported, the Inspector lets you choose the exact anchor when several share one frame.
-Script order and physical time can differ when Takes overlap or are reordered.
+```svml
+<semantic:Projection id="story-time" narrative={story} timeline={film.timeline}>
+ <semantic:Map alignment={speech.alignment} domain={speech-media.domain} window={film.speech}/>
+ <semantic:Window id="proof" selection={story.selection.proof}/>
+ <semantic:Instant id="reveal" moment={story.moment.reveal}/>
+</semantic:Projection>
-Marker edits preserve unrelated prose, spaces, punctuation, pronunciation and word attributes.
-Caption Cues keep their Script-derived content and measured word times. Change their wording or
-Cue boundaries in Script, and their appearance through the Caption Style and timed Uses.
+<visual:Clip during={story-time.proof} .../>
+<deck:Card at={story-time.reveal} .../>
+```
-Unedited expressions retain their units: `2s` keeps its duration across frame rates, while `60f`
-keeps its frame count. A clock position or offset changed by a drag is written in whole frames
-at the current frame rate.
+The Narrative projection declaration retains the Selection or Moment relation required by its
+Companion. Editing that declaration may move Script anchors, and every consumer follows after recompilation.
+The consumers themselves receive only completed absolute values. A future beat projector can offer
+different editing rules while publishing the same Temporal types.
-## Editing a project component
+If a producer declares no inverse, the resolved value remains usable but Studio does not guess a
+write target. This keeps shared meaning, local clock values and component behavior separate.
-A component's Companion connects its entities to their actual authored inputs and projected time.
-The time form determines the edit target; the component name or a coincident frame does not.
-Source observation and marker relocation belong to the Script Companion. Adding a new component
-therefore does not require teaching Studio another interpretation of Script.
+Unedited expressions retain their units: `2s` remains two seconds when frame rate changes, whereas
+`60f` remains sixty frames. A changed clock value is written on a whole frame boundary for the
+current Timeline.
[Studio](../quickstart/preview.md) explains the editing interface. The
-[Companion guide](./studio-companion-architecture.md) explains exposing entities and controls;
-the package-owned [temporal editing reference](https://github.com/hypit-ai/hypit/blob/main/packages/temporal-markup/EDITING.md)
-contains the exact implementation interfaces and supported operations.
+[Companion guide](./studio-companion-architecture.md) explains package-owned entities and controls.
diff --git a/docs/quickstart/composition.md b/docs/quickstart/composition.md
index 969fff21..54c2293d 100644
--- a/docs/quickstart/composition.md
+++ b/docs/quickstart/composition.md
@@ -1,10 +1,11 @@
---
title: Film & Rendering
-description: Composing tracks into a film and rendering to video.
+description: Assemble peer visual and audio contributions, then render the selected program range.
---
-Film is the final assembly stage. It takes all peer Tracks, validates them, and produces a
-Composition. The renderer then compiles that Composition into an MP4 video.
+Film is an ordinary author component. It combines explicitly selected VisualTrack and AudioTrack
+outputs with one Canvas and one Timeline, producing a Composition. The renderer turns that
+Composition into a video.
```svml
<import as="space" from="@hypit/spatial@1"/>
@@ -12,301 +13,131 @@ Composition. The renderer then compiles that Composition into an MP4 video.
<import as="render" from="@hypit/render-hyperframes@1"/>
```
-## film:Film
-
-Assembles selected VisualTracks and AudioTracks into a single Composition. Each visual contribution
-retains its own timed appearances and paint order; sound is included through the selected AudioTracks.
+## Assemble the Film
```svml
<space:Canvas id="vertical" width="1080" height="1920"/>
-<import as="sound" from="@hypit/sound@1"/>
-<sound:Style id="voice-style"/>
-<sound:Track id="voice" timeline={speech.timeline}>
- <sound:Use style={voice-style}/>
-</sound:Track>
-
-<film:Film id="main" canvas={vertical} timeline={speech.timeline} appearance={recipes.film.vertical}>
- <film:Track source={performance.visual}/>
- <film:Track source={voice.audio}/>
- <film:Track source={captions.track}/>
- <film:Track source={product-broll.visual}/>
- <film:Track source={titles.track}/>
+
+<film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline}
+ appearance={recipes.film.vertical}>
+ <film:Track source={picture.visual}/>
+ <film:Track source={mix.audio}/>
+ <film:Track source={cards.visual}/>
+ <film:Track source={captions.visual}/>
+ <film:Track source={meaning.visual}/>
</film:Film>
```
-| Attribute | Required | Description |
+| Attribute | Required | Meaning |
|---|---|---|
-| `id` | yes | Unique identifier |
-| `canvas` | yes | Explicit CanvasSpace shared with Track layout |
-| `timeline` | yes | Complete Timeline, with any prepared material and semantic anchors |
-| `appearance` | yes | SVS Film Recipe — the canvas clear color |
-
-### film:Track
+| `id` | yes | Public composition identity |
+| `canvas` | yes | The picture coordinate system |
+| `timeline` | yes | The finite absolute program range |
+| `appearance` | yes | Film Recipe, including the clear color |
-Each `<film:Track>` child adds a Track source to the composition:
+Each `<film:Track>` accepts one VisualTrack or AudioTrack. Film does not discover sibling outputs.
+If one normalized source should contribute both picture and sound, author one Visual Clip and one
+Audio Clip from that media; both resulting Tracks must then be selected here.
-| Attribute | Required | Description |
-|---|---|---|
-| `source` | yes | A VisualTrack or AudioTrack from any upstream component |
-
-Common Track sources:
+Common outputs include:
-| Source | Type | From |
+| Source | Type | Role |
|---|---|---|
-| `{performance.visual}` | VisualTrack | `performance:Track` — presentation of existing footage |
-| `{voice.audio}` | AudioTrack | `sound:Track` — presentation of existing audio |
-| `{captions.track}` | VisualTrack | a Caption Style-family Track — timed captions |
-| `{cards.visual}` | VisualTrack | `media-track:Track` — media overlays or B-roll |
-| `{titles.track}` | VisualTrack | `text:Track` — text overlays |
+| `{picture.visual}` | VisualTrack | picture occurrences placed by Visual Track |
+| `{mix.audio}` | AudioTrack | placed voices, music and effects from Audio Track |
+| `{cards.visual}` | VisualTrack | independent image/video Clips |
+| `{captions.visual}` | VisualTrack | a Caption family |
+| `{scene.visual}` | VisualTrack | a project component |
-### Track stacking
+The public output is `{main.composition}`.
-Film collects peer Tracks. Each Track can contain several independently timed and ordered
-appearances, called Presents. Many components expose that paint order as `stack-order` in their
-Recipe: lower values paint behind higher values. Reordering Film children leaves this order intact.
+## Visual order belongs to Presents
-Typical stacking order:
+Film children select contributions; their source order does not define picture stacking. Each visual
+component publishes timed Presents with an absolute `z`, commonly authored through `stack-order` in
+its Recipe. Lower values paint behind higher values. Equal values use stable Track identity, then
+Track-local Present `order` and Present identity; use distinct values whenever the relative paint
+relation matters.
-| stack-order | Content |
-|---|---|
-| 10 | Performance presentation (author-selected) |
-| 40 | Media overlays |
-| 70 | Captions |
-| 90 | Text overlays |
+```svs
+film.vertical { background: #09090B; }
+media.speaker { stack-order: 10; fit: cover; }
+media.card { stack-order: 40; fit: contain; }
+caption.base { stack-order: 70; }
+/* Fine Text writes z="90" on its Flow, Point or Path occurrence. */
+```
-Presents from different components can interleave. Each Present also owns an internal element tree:
-several videos, text and graphics can share layout, masks or coordinated motion. A project component
-can use an HTML/CSS browser program for such a scene. Independent Caption or coverage can remain
-peer contributions. Group the content whose behavior belongs together; its size and media type do
-not prescribe that boundary.
+Presents from different Tracks can interleave. A Present may also own an internal element tree or a
+browser program when several pictures, graphics and text share layout or motion. Put content together
+when its behavior belongs together; keep independently useful contributions as peers.
-**Output:** `{main.composition}` — the complete Composition, passed to the renderer.
+## Render the complete video
-## render:Video
+```svml
+<render:Video id="final"
+ composition={main.composition} timeline={speech.timeline}/>
+```
-Compiles the Composition into a finished video via the HyperFrames renderer.
+The renderer compiles the visual contributions, captures requested frames, renders AudioTracks and
+muxes them into the delivered file. `{final.video}` is an ordinary Resource-backed `BlobArtifact` and
+the usual Run Target.
```svml
-<render:Video id="final" composition={main.composition} timeline={speech.timeline}/>
+<?svml using="@hypit/run-markup@1"?>
+<svrun version="1">
+ <author source="./main.svml"/>
+ <target output="final.video"/>
+</svrun>
```
-| Attribute | Required | Description |
-|---|---|---|
-| `id` | yes | Unique identifier |
-| `composition` | yes | Composition from `film:Film` |
-| `timeline` | yes | Complete Timeline, with any prepared material and semantic anchors |
-
-The renderer:
+## Render a frame interval
-1. Compiles the Composition into a `HyperframesDocument` — an HTML representation of every frame
-2. Renders each frame through Chrome/Chromium
-3. Encodes the frame sequence into video
-4. Mixes the audio Tracks
-5. Muxes video + audio into the final MP4
+```svml
+<render:Video id="detail" composition={main.composition} timeline={speech.timeline}
+ start-frame="240" end-frame-exclusive="360"/>
+```
-**Output:** `{final.video}` — the finished video as an ordinary Resource-backed `BlobArtifact`.
-This is the most common Build Target, and it can also be connected directly to later Blob consumers
-such as media trimming, audio/frame extraction or a model reference input.
+The bounds use the original Timeline and a half-open interval. At 30 fps this example renders
+seconds 8–12. Animation and media sampling retain their original program positions even though the
+encoded clip starts at zero. Range rendering limits final capture and encoding; upstream graph work
+still follows the selected Run, so reuse accepted media and alignment Outputs explicitly.
## A film drawn entirely by components
-For spoken work, Script Selections and Moments preserve the relationship between the words and
-their presentation. A chat animation or diagram can instead direct its own reading rhythm. Declare
-the film clock and use it in the scene, Film and Render:
+Timeline does not require speech or media:
```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"/>
-<!-- scene.track is produced by a component using this same clock. -->
-<film:Film id="main" canvas={canvas} timeline={animation.timeline} appearance={recipes.film.main}>
- <film:Track source={scene.track}/>
-</film:Film>
-<render:Video id="final" composition={main.composition} timeline={animation.timeline}/>
-```
-The scene's events can use authored seconds or frames. In a spoken composition, the same behavior
-can follow projected Script events instead. The component draws the picture directly; no background
-image or silent performance is needed to establish duration. With no selected AudioTrack, the
-delivered video is silent.
+<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."/>
+</chat:Scene>
-## Full pipeline walkthrough
-
-The complete data flow from Script to rendered video. The Sources below are an abridged
-illustration. The complete runnable project is `examples/podcast/`; the commands below use it.
-
-### Author Source (`main.svml`)
-
-```svml
-<?svml using="@hypit/markup@1"?>
-
-<svml>
- <import from="@hypit/script@1"/>
- <import as="wording" from="@hypit/text@1"/>
- <import as="gpt" from="@hypit/gpt-image@1"/>
- <import as="seedance" from="@hypit/seedance@1"/>
- <import as="pipeline" from="@hypit/media-pipeline@1"/>
- <import as="time" from="@hypit/timeline-author@1"/>
- <import as="whisperx" from="@hypit/whisperx@1"/>
- <import as="caption" from="@hypit/caption@1"/>
- <import as="caption-fine" from="@hypit/caption-fine@1"/>
- <import as="fonts" from="@hypit/fonts-open@1"/>
- <import as="media-track" from="@hypit/media-track@1"/>
- <import as="performance" from="@hypit/performance@1"/>
- <import as="text" from="@hypit/typography-track@1"/>
- <import as="space" from="@hypit/spatial@1"/>
- <import as="program" from="@hypit/program-space@1"/>
- <import as="film" from="@hypit/film@1"/>
- <import as="render" from="@hypit/render-hyperframes@1"/>
- <import as="recipes" source="./recipes.svs"/>
-
- <!-- 1. Script: the semantic truth -->
- <script id="story">
- <opening><HOST>Meaning @{demo}becomes the source.@{/demo}</opening>
- </script>
-
- <!-- 2. Generation: Seedance talking head + standalone video -->
- <wording:Value id="direction">
- Locked medium close-up in a quiet daylight studio. Spoken dialogue — say exactly: Meaning becomes the source.
- </wording:Value>
- <wording:Value id="scene-look">
- A photograph with the texture of real iPhone footage. Generate a vertical seated medium
- close-up, as one frame cut out of video actually shot on an iPhone: genuinely real rather than
- glossy, carrying the texture of video and not of a posed photograph. The background stays clearly
- visible, with no depth-of-field blur. Skin texture is fine and real, the light is natural, and no
- part of the picture is broken. One presenter at a desk in a quiet daylight studio.
- </wording:Value>
- <gpt:Image id="studio-scene" prompt={scene-look} aspect-ratio="9:16" resolution="2K"/>
- <seedance:ReferenceVideo id="take" model="mini"
- prompt={direction} duration="5" generate-audio="true">
- <seedance:Reference image={studio-scene.image} person-reference="true"/>
- </seedance:ReferenceVideo>
- <seedance:ReferenceVideo id="motion" model="mini"
- prompt={direction} duration="5">
- <seedance:Reference image={studio-scene.image} person-reference="true"/>
- </seedance:ReferenceVideo>
-
- <space:Canvas id="vertical" width="1080" height="1920"/>
- <program:Clock id="clock" frame-rate="30"/>
- <space:Frame id="speech-frame" within={vertical}
- left="0%" top="0%" right="100%" bottom="100%"/>
- <space:Frame id="title-frame" within={vertical}
- left="6%" top="6%" right="94%" bottom="16%"/>
- <space:Frame id="card-frame" within={vertical}
- left="10%" top="20%" right="90%" bottom="70%"/>
-
- <!-- 3. Timing: normalize and align the Segment before assembly -->
- <pipeline:Normalize id="take-media" source={take.video}
- video="primary-moving" audio="default" span-authority="video" clock={clock}/>
- <pipeline:Normalize id="motion-media" source={motion.video}
- video="primary-moving" audio="none" span-authority="video" clock={clock}/>
- <whisperx:SemanticTake id="opening-semantic" narrative={story}
- segment={story.segment.opening} media={take-media.media} language="en"/>
- <time:Timeline id="speech" clock={clock}>
- <time:Take source={opening-semantic.take}/>
- </time:Timeline>
-<performance:Style id="performance-style" frame={speech-frame} appearance={recipes.media.performance}/>
- <performance:Track id="performance" timeline={speech.timeline} canvas={vertical}>
- <performance:Use style={performance-style} during="program"/>
- </performance:Track>
-
- <!-- 4. Tracks: captions, Media, text -->
- <fonts:Stack id="caption-font" family="inter" weight="700" style="normal"/>
- <fonts:Stack id="title-font" family="inter" weight="900" style="normal"/>
- <caption-fine:Style id="base-caption" recipe={recipes.caption.base} font={caption-font}/>
-
- <caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline}>
- <caption-fine:Use style={base-caption}/>
- </caption-fine:Track>
-
- <media-track:Track id="cards" timeline={speech.timeline} canvas={vertical}>
- <media-track:Item media={motion-media.media} during={story.selection.demo}
- frame={card-frame} appearance={recipes.media.card} motion={recipes.motion.card}/>
- </media-track:Track>
- <text:Style id="title-style" recipe={recipes.text.title} font={title-font}/>
- <text:Track id="titles" timeline={speech.timeline}>
- <text:Area id="meaning" placement={title-frame} style={title-style} during="program">
- MEANING
- </text:Area>
- </text:Track>
-
- <!-- 5. Film: compose all tracks -->
- <import as="sound" from="@hypit/sound@1"/>
-<sound:Style id="voice-style"/>
-<sound:Track id="voice" timeline={speech.timeline}>
- <sound:Use style={voice-style}/>
-</sound:Track>
-
-<film:Film id="main" canvas={vertical} timeline={speech.timeline}
- appearance={recipes.film.vertical}>
- <film:Track source={performance.visual}/>
- <film:Track source={voice.audio}/>
- <film:Track source={cards.visual}/>
- <film:Track source={captions.track}/>
- <film:Track source={titles.track}/>
- </film:Film>
-
- <!-- 6. Render: compile to MP4 -->
- <render:Video id="final" composition={main.composition}
- timeline={speech.timeline}/>
-</svml>
-```
-
-`right` and `bottom` are absolute edge positions, not insets. A Frame spanning the middle 80% of
-its parent is `left="10%" right="90%"`, not `left="10%" right="10%"` — the second resolves to zero
-width and is rejected.
-
-### Stylesheet (`recipes.svs`)
-
-```svs
-<?svml using="@hypit/svs@1"?>
-
-<sheet version="1">
- film.vertical {
- background: #09090B;
- }
- media.performance { stack-order: 0; fit: cover; }
- media.card {
- stack-order: 40; fit: cover; playback: hold-start;
- frame-paint: #111116; clip: rounded; radius: 20;
- }
- motion.card {
- enter: slide; enter-frames: 4; enter-direction: up; enter-easing: ease-out;
- exit: fade; exit-frames: 4; exit-easing: ease-in;
- }
- caption.base {
- stack-order: 70; x: 0.08; y: 0.76; width: 0.84;
- size: 58; line-height: 1; align: center;
- fill: #FFFFFF; background: #09090BCC; padding: 16 24; radius: 18;
- }
- text.title {
- stack-order: 90;
- font: Inter; weight: 900; size: 64; align: center;
- fill: #FFFFFF; tracking: -1;
- }
-</sheet>
+<film:Film id="main" canvas={canvas.canvas} timeline={animation.timeline}
+ appearance={recipes.film.main}>
+ <film:Track source={conversation.visual}/>
+</film:Film>
+<render:Video id="final" composition={main.composition} timeline={animation.timeline}/>
```
-### Run Source (`build.svrun`)
+The component owns its reading rhythm through ordinary absolute time. With no selected AudioTrack,
+the result is silent. A spoken composition can use the same component with semantic Moments or
+Selections projected onto its Timeline.
-```svml
-<?svml using="@hypit/run-markup@1"?>
-
-<svrun version="1">
- <author source="./main.svml"/>
- <target output="final.video"/>
-</svrun>
-```
-
-### Compile and verify
+## Check before execution
```bash
-hypit check examples/podcast/reference.svml
-
-hypit plan examples/podcast/reference.svrun
+hypit check main.svml
+hypit plan build.svrun
```
-`check` compiles the Author Graph — validates all imports, types, and graph edges without calling
-any external service. `plan` additionally compiles the Run Source and outputs the frozen BuildPlan
-showing every Operation the Scheduler would issue. Inspect the plan before spending money.
+`check` validates imports, types and graph edges without calling external services. `plan` compiles
+the selected Run and shows the Operations it would demand. Inspect that plan before paid execution.
+
+See [Timing & Assembly](./timing.md) for normalization, Timeline construction, media presentation and
+semantic projection. See [Tracks](./tracks.md) for Visual and Audio authoring forms.
diff --git a/docs/quickstart/images.md b/docs/quickstart/images.md
index 03fda794..41d8a0a3 100644
--- a/docs/quickstart/images.md
+++ b/docs/quickstart/images.md
@@ -4,7 +4,7 @@ description: Compose, correct and cut out images before they reach a generator o
---
Three packages work on a picture and hand back a picture. None of them produces a Track: each output
-is an image you reference downstream — as a Seedance reference frame, as a Media Item, or as the
+is an image you reference downstream — as a Seedance reference frame, as a Visual Clip, or as the
source of another operation.
They all need an endpoint. `image-compose` and `image-transform` ask for the raster capability, which
@@ -33,7 +33,7 @@ most sixty-four, each empty:
| `opacity` | optional — 0 to 1, default 1 |
```svml
-<compose:Image id="card" canvas={portrait} background="#00000000">
+<compose:Image id="card" canvas={portrait.canvas} background="#00000000">
<compose:Layer source={background.image} frame={full} fit="cover"/>
<compose:Layer source={product.image} frame={product-frame} fit="contain"/>
</compose:Image>
@@ -95,7 +95,7 @@ that is the endpoint's business, not the Source's.
<remove:Background id="cutout" source={portrait.image}/>
```
-**Output:** `{cutout.image}` — typically fed to a Media Item so a presenter sits over the picture
+**Output:** `{cutout.image}` — typically fed to a Visual Clip so a presenter sits over the picture
rather than in a box.
## Removing a moving person's background
@@ -109,8 +109,7 @@ served by a supporting HypiHub Endpoint:
<matte:Portrait id="cutout" source={performance.video}/>
```
-Normalize `cutout.video` to prepare it for the timeline. If it establishes the spoken program,
-align that prepared media to its Script Segment and assemble it through Timeline assembly. Present the
-picture with Media Track or a project scene, at the chosen location and paint order. As B-roll,
-the normalized cutout can enter Media Track directly. Matting changes the picture's background;
-the composition determines its role.
+Normalize `cutout.video` to obtain synchronized media and its local domain. If it carries spoken
+meaning, align that local domain to its Script Segment, then project the alignment through the
+equal-length Timeline Window. Place the normalized cutout as an ordinary Visual Clip. Matting changes the picture's
+background; the composition determines its role.
diff --git a/docs/quickstart/run.md b/docs/quickstart/run.md
index 39ffa9a1..6878778b 100644
--- a/docs/quickstart/run.md
+++ b/docs/quickstart/run.md
@@ -199,10 +199,11 @@ Connects a Candidate to a Logical Output:
The Planner reads the complete Author Graph and Run Graph together. It prunes default Operations
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 semantic
-preparation downstream; reusing a prepared SemanticTake retains those results too. Caption, MG and
-rendering recompute where they remain on the selected route. Choose the Output whose meaning matches
-what should stay unchanged.
+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
+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.
Core does not label a Candidate as “exact” or “substitute”. Choosing a Candidate is the Run
author's explicit implementation decision for that Build. Type compatibility is checked; creative
diff --git a/docs/quickstart/script.md b/docs/quickstart/script.md
index 81fef56f..82cfc3f7 100644
--- a/docs/quickstart/script.md
+++ b/docs/quickstart/script.md
@@ -128,7 +128,7 @@ as `<API|...>` supplies no timed correspondence and is invalid.
`||` is the **Caption Cue Break** syntax. It records a boundary between complete Alignment Units;
it cannot appear inside Dual Text or split an N:M unit. Cue timing is still obtained later by
-joining the CaptionDocument to the Timeline.
+projecting its peer NarrativeCaptionBinding through explicit Narrative time.
### Spaces and spelling
@@ -156,7 +156,7 @@ Caption Style; attributes do not split, wrap or retime a Dual Alignment Unit.
### CaptionDocument vocabulary
-`CaptionDocument` is the Script-owned caption truth. Its named parts are:
+`CaptionDocument` is a Caption-owned display value that Script can produce from the same source. Its named parts are:
- **Display Word** — one rendered lexical surface, including display punctuation;
- **Alignment Unit** — the smallest display-to-speech correspondence, including N:M Dual Text;
diff --git a/docs/quickstart/styles.md b/docs/quickstart/styles.md
index 285727e7..948ba469 100644
--- a/docs/quickstart/styles.md
+++ b/docs/quickstart/styles.md
@@ -60,7 +60,7 @@ Referenced by `film:Film` via the `appearance` attribute:
```svml
<space:Canvas id="vertical" width="1080" height="1920"/>
-<film:Film id="main" canvas={vertical} timeline={speech.timeline} appearance={recipes.film.vertical}>
+<film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline} appearance={recipes.film.vertical}>
```
## Caption Fine
@@ -140,24 +140,24 @@ Then select them with timed Uses in the Track:
<caption-fine:Style id="default-caption" recipe={recipes.caption.dialogue} font={caption-font}/>
<caption-fine:Style id="alice-caption" recipe={recipes.caption.alice} font={caption-font}/>
<caption-fine:Style id="bob-caption" recipe={recipes.caption.bob} font={caption-font}/>
-<caption-fine:Track id="captions" document={story.caption} timeline={speech.timeline}>
+<caption-fine:Caption id="captions" document={story.caption} timing={story-captions}
+ timeline={speech.timeline} within={vertical.bounds}>
<caption-fine:Use style={default-caption}/>
<caption-fine:Use role="ALICE" style={alice-caption}/>
<caption-fine:Use role="BOB" style={bob-caption}/>
-</caption-fine:Track>
+</caption-fine:Caption>
```
-## Media Track
+## Visual Track Clips
-Media keeps spatial placement, frame presentation and lifecycle motion separate. A `SpatialFrame`
-owns position and size; the appearance Recipe owns fitting and the frame material; an optional
-motion Recipe owns enter, sustain and exit behavior.
+Visual Clips keep space, source-time, pixel treatment and local motion separate. A `SpatialFrame`
+owns position and size. `z`, fitting and the optional partial source-time relation are direct facts
+of this occurrence. A
+treatment Recipe may reuse image and Frame paint, while a typed Motion is reusable affine/opacity
+keyframes rather than a closed effect name.
```svs
-media.product {
- stack-order: 40;
- fit: contain;
- playback: hold-start;
+visual.product {
frame-paint: #111116;
clip: rounded;
radius: 28;
@@ -167,51 +167,51 @@ media.product {
border-color: #FFFFFF20;
shadows: 0 10 24 0 #00000066;
}
-
-motion.product {
- enter: slide;
- enter-frames: 8;
- enter-direction: up;
- enter-easing: ease-out;
- exit: fade;
- exit-frames: 6;
- exit-easing: ease-in;
-}
```
| Property | Description |
|---|---|
-| `stack-order` | Z-stacking order |
-| `fit` | `contain`, `cover`, `fit-width`, `fit-height`, `native`, `scale-down`, or `stretch` |
+| `z` | Direct Z-stacking order; equal values use stable declaration and identity order |
+| `fit` | Direct `contain`, `cover`, `fit-width`, `fit-height`, `native`, `scale-down`, or `stretch` |
| `frame-x`, `frame-y` | Alignment point inside the placement Frame |
| `content-x`, `content-y` | Independently selected focal point inside the source |
-| `playback` | Timed-source occupancy such as `once-start`, `hold-start`, `loop-end`, or `stretch` |
+| `source-time` / `Map` | Reusable or inline partial mapping for timed-source coordinates |
| `frame-paint` | Solid or gradient Paint behind the sampled source |
| `clip`, `radius`, `padding` | Frame clipping and inset |
| `border-*`, `shadows` | Frame-owned border and ordered shadows |
-| `enter`, `exit` | Lifecycle operator; its frame count, easing and direction use separate properties |
-| `sustain` | Zero or more deterministic local motions such as `float 12 2 up` |
+| `motion` / `Pose` | Optional typed affine and opacity states over the Clip-local clock |
Position remains an explicit graph edge:
```svml
-<space:Frame id="product-frame" within={vertical}
+<space:Frame id="product-frame" within={vertical.bounds}
left="8%" top="20%" right="92%" bottom="68%"/>
-<media-track:Item media={product-media.media}
- during={story.selection.demo} frame={product-frame}
- appearance={recipes.media.product} motion={recipes.motion.product}/>
+<visual:Motion id="product-in">
+ <visual:Pose at="start" y="80" opacity="0" easing="ease-out"/>
+ <visual:Pose at="8f" y="0" opacity="1"/>
+ <visual:Pose at="end" y="0" opacity="1"/>
+</visual:Motion>
+<visual:Clip media={product-media.media}
+ during={story-time.demo} frame={product-frame}
+ z="40" fit="contain"
+ treatment={recipes.visual.product} motion={product-in}>
+ <visual:Map/>
+</visual:Clip>
```
+If a behavior coordinates several objects, changes structure or gives a source a new visual role,
+author a component. Motion is the shared mathematical substrate, not a catalogue of every effect a
+video may ever need.
+
## Text
-Text overlay appearance — typography and Paint. Placement is a separate `SpatialFrame` graph edge.
+Fine Text Style owns reusable typography and Paint only. The occurrence itself owns geometry,
+form-specific layout and absolute `z`, because those facts change from one use of a Style to another.
```svs
text.title {
- stack-order: 90;
weight: 900;
size: 64;
- align: center;
fill: #FFFFFF;
tracking: -1;
}
@@ -219,10 +219,8 @@ text.title {
| Property | Description |
|---|---|
-| `stack-order` | Z-stacking order |
| `weight` | Font weight |
| `size` | Font size in pixels |
-| `align` | Text alignment |
| `fill` | Text color |
| `tracking` | Letter spacing adjustment |
@@ -231,9 +229,10 @@ Compiled with exact font bytes into a `text:Style`, then referenced by a concret
```svml
<fonts:Stack id="title-font" family="inter" weight="900" style="normal"/>
<text:Style id="title-style" recipe={recipes.text.title} font={title-font}/>
-<text:Area id="meaning" placement={title-frame} style={title-style} during="program">
+<text:Flow id="meaning" timeline={speech.timeline} within={title-frame}
+ style={title-style} z="90" align="center" during="timeline">
MEANING
-</text:Area>
+</text:Flow>
```
## Speaker Text Template
@@ -401,5 +400,5 @@ This file is imported once in the `.svml` source and its values are referenced t
<caption-fine:Style id="primary-caption" recipe={recipes.caption.primary} font={caption-font}/>
<space:Canvas id="vertical" width="720" height="1280"/>
-<film:Film id="main" canvas={vertical} timeline={speech.timeline} appearance={recipes.film.vertical}>
+<film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline} appearance={recipes.film.vertical}>
```
diff --git a/docs/quickstart/timing.md b/docs/quickstart/timing.md
index 5b7c3277..deb21661 100644
--- a/docs/quickstart/timing.md
+++ b/docs/quickstart/timing.md
@@ -1,149 +1,127 @@
---
title: Timing & Assembly
-description: Per-take normalization and alignment, followed by Timeline assembly.
+description: Construct absolute program time, then present media and project optional semantic time explicitly.
---
-For spoken video, a `Timeline` connects the authored Script to the actual performance. This is
-the natural time source for captions, word-triggered graphics and coverage. Build it in segment-sized pieces:
+Hypit has one program-time axis: `Timeline`. It is only `{ id, frameRate, frameCount }`.
+It contains no clips, words, Tracks or central event registry.
-1. normalize each accepted A/V take into one exact frame domain;
-2. align that normalized media with its authored Script Segment to create a self-contained `SemanticTake`;
-3. assemble the Semantic Takes in program order with `time:Timeline`.
+For spoken work, four independent facts meet around that axis:
-Every Take is already semantic before it enters the Timeline assembly. Pictures can be presented by
-Media Track or a project component independently of this semantic and audio assembly.
+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.
-A purely visual animation uses the same Timeline with an explicit end and zero Takes.
-See [an authored film clock](./composition.md#a-film-drawn-entirely-by-components). It can use seconds
-or frames for events; spoken work can use Script Selections and Moments for the same visual behavior.
+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
+or Script.
```svml
-<import as="program" from="@hypit/program-space@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
+<import as="semantic" from="@hypit/narrative-temporal@1"/>
<import as="time" from="@hypit/timeline-author@1"/>
-<import as="media-track" from="@hypit/media-track@1"/>
- <import as="performance" from="@hypit/performance@1"/>
-<import as="space" from="@hypit/spatial@1"/>
-<import as="recipes" source="./recipes.svs"/>
+<import as="media" from="@hypit/media@1"/>
+<import as="visual" from="@hypit/visual-track@1"/>
+<import as="audio" from="@hypit/audio-track@1"/>
```
-## Normalize each take
+## Normalize local media
-Normalization makes video, audio, duration and frame rate one explicit `SynchronizedMedia` fact.
-The Clock is authored once and shared by every Take that will enter the same Timeline.
+The Clock fixes the frame rate shared by the final Timeline and every local domain placed on it:
```svml
-<program:Clock id="clock" frame-rate="30"/>
-
+<time:Clock id="clock" frame-rate="30"/>
<pipeline:Normalize id="opening-media" source={opening-video.video}
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
<pipeline:Normalize id="answer-media" source={answer-video.video}
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
```
-Normalization contains no Script meaning and performs no transcription. It only establishes the
-media facts that later semantic alignment can trust.
-
-## Create one SemanticTake per Segment
+Normalization establishes media facts. It contains no Script meaning or program placement.
-`whisperx:SemanticTake` measures one normalized Take and aligns the evidence with exactly one
-authored Segment:
+## Align meaning on each local domain
```svml
-<whisperx:SemanticTake id="opening-semantic" narrative={story}
- segment={story.segment.opening} media={opening-media.media} language="en"/>
-<whisperx:SemanticTake id="answer-semantic" narrative={story}
- segment={story.segment.answer} media={answer-media.media} language="en"/>
+<whisperx:Alignment id="opening-alignment" narrative={story}
+ segment={story.segment.opening} media={opening-media.media}
+ domain={opening-media.domain} language="en"/>
+<whisperx:Alignment id="answer-alignment" narrative={story}
+ segment={story.segment.answer} media={answer-media.media}
+ domain={answer-media.domain} language="en"/>
```
-For a Segment with spoken words, `language` explicitly names its spoken language, such as `en`,
-`zh` or `ko`. Use a lowercase two- or three-letter code supported by the selected WhisperX service.
-It is passed unchanged; Hypit does not detect or route languages from Script text or audio.
-An empty Segment omits `language` and uses the normalized media boundaries directly.
-
-Each output contains the normalized media, the Segment identity, every authored word's local frame
-window, and all of that Segment's structural anchors. There are two anchors for the Segment and two
-for each word. Acoustic evidence is an implementation input to this step; downstream components see
-the completed `SemanticTake`, not a second evidence-shaped timing structure.
+Each output is only a `NarrativeAlignment`: Segment and word boundaries measured on that local
+domain. It does not contain media and does not choose a Timeline position. A Segment with no Tokens
+omits `language`; its boundaries are the local domain boundaries and no acoustic request is needed.
-## Assemble the Timeline
+## Construct the absolute Timeline
-`time:Timeline` places prepared Takes sequentially by default, or at authored `at` positions,
-and provides the complete Timeline. Performance and Sound present its pictures and audio separately:
+Timeline authoring is an acyclic construction graph. `end` is required; every named Instant or
+Window is naturally published as an ordinary graph value:
```svml
-<space:Canvas id="vertical" width="1080" height="1920"/>
-<space:Frame id="speech-frame" within={vertical}
- left="0%" top="0%" right="100%" bottom="100%"/>
-
-<time:Timeline id="speech" clock={clock}>
- <time:Take source={opening-semantic.take}/>
- <time:Take source={answer-semantic.take}/>
+<time:Timeline id="speech" clock={clock} end="answer.end">
+ <time:Window id="opening" from="start" for={opening-media.extent}/>
+ <time:Window id="answer" from="opening.end" for={answer-media.extent}/>
</time:Timeline>
-<import as="sound" from="@hypit/sound@1"/>
-<sound:Style id="voice-style"/>
-<sound:Track id="voice" timeline={speech.timeline}>
- <sound:Use style={voice-style}/>
-</sound:Track>
-<performance:Style id="performance-style" frame={speech-frame} appearance={recipes.media.performance}/>
- <performance:Track id="performance" timeline={speech.timeline} canvas={vertical}>
- <performance:Use style={performance-style} during="program"/>
- </performance:Track>
```
-| Output | Type | Meaning |
-|---|---|---|
-| `{speech.timeline}` | Timeline | Global semantic and frame-domain authority |
-| `{voice.audio}` | AudioTrack | Sound presentation of the placed Takes |
+Each `for={...extent}` uses a resolved unpositioned duration. Generated speech may therefore
+determine Timeline length during ordinary graph evaluation. Use `from="opening.end+2s"` for a gap,
+`from="opening.end-12f"` for overlap, or `latest(a.end,b.end)` for parallel branches. A pure animation
+can simply declare `<time:Timeline id="animation" clock={clock} end="8s"/>`. The Timeline retains no
+media or source-domain identity.
-Performance and Sound use the same prepared Takes and source positions.
-Each Take's global frames are its placement start plus its local frames. The first omitted `at` is
-zero; later omitted `at` follows the preceding Take's end. Use `at="previous.end+2s"` for a gap,
-`at="previous.end-12f"` for overlap, or an absolute position. Timeline `end` defaults to the latest
-content end; `end="content.end+2s"` reserves a tail and `end="30s"` declares a fixed extent.
-All positions resolve to exact frames and the extent contains all Takes. Empty Timelines require
-an authored positive end. No placeholder media fills uncovered time.
+## Project meaning independently
-## Consume semantic time
+Project semantic evidence by pairing each Alignment with its complete local domain and equal-length
+absolute Window:
-Selections, Moments and whole Segments remain authored Script identities. A downstream component
-receives the Timeline once and projects those identities into frames only when it builds its
-deterministic Track:
+```svml
+<semantic:Projection id="story-time" narrative={story} timeline={speech.timeline}>
+ <semantic:Map alignment={opening-alignment.alignment}
+ domain={opening-media.domain} window={speech.opening}/>
+ <semantic:Map alignment={answer-alignment.alignment}
+ domain={answer-media.domain} window={speech.answer}/>
+ <semantic:Window id="proof" selection={story.selection.proof}/>
+ <semantic:Instant id="claim" moment={story.moment.claim}/>
+</semantic:Projection>
+```
+
+The requested outputs `story-time.proof` and `story-time.claim` are ordinary absolute Window and
+Instant values. Semantic time is one
+optional projection source; direct seconds, frames and named Timeline values remain equally valid.
+
+## Present picture and audio
```svml
-<media-track:Track id="cards" timeline={speech.timeline} canvas={vertical}>
- <media-track:Item image={card.image} extent={card-extent}
- during={story.selection.demo} frame={card-frame}
- appearance={recipes.media.card} motion={recipes.motion.card}/>
-</media-track:Track>
-
-<caption-fine:Track id="captions"
- document={story.caption}
- timeline={speech.timeline}
->
- <caption-fine:Use style={primary-caption}/>
-</caption-fine:Track>
-
-<film:Film id="main" canvas={vertical}
- timeline={speech.timeline} appearance={recipes.film.vertical}>
- <film:Track source={performance.visual}/>
- <film:Track source={voice.audio}/>
- <film:Track source={cards.visual}/>
- <film:Track source={captions.track}/>
-</film:Film>
-
-<render:Video id="final"
- composition={main.composition} timeline={speech.timeline}/>
+<visual:Track id="picture" timeline={speech.timeline}>
+ <visual:Clip id="opening" media={opening-media.media} during={speech.opening}
+ frame={speech-frame} z="10" fit="cover"/>
+ <visual:Clip id="answer" media={answer-media.media} during={speech.answer}
+ frame={speech-frame} z="10" fit="cover"/>
+</visual:Track>
+
+<audio:Track id="mix" timeline={speech.timeline}>
+ <audio:Clip id="opening" source={opening-media.media} during={speech.opening}/>
+ <audio:Clip id="answer" source={answer-media.media} during={speech.answer}/>
+</audio:Track>
```
-Use `during={story.segment.answer}` for a whole Segment, a Selection for an authored range, a Moment
-for a point event, and `during="program"` for the complete Timeline domain. Components consume
-`timeline={speech.timeline}`.
+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
+audible automatically.
```text
-prepared Takes → Timeline → Performance / project scene → visual ─┐
- ├→ Caption / semantic graphics → visual ┤
- └→ Sound → audio ───────────────────────┤
- Film
+SynchronizedMedia + Window ──────────────────────────────→ Visual / Audio occurrence
+
+NarrativeAlignment + LocalDomain + Window ──────────────→ absolute Instants / Windows
+
+Instant / Window / TemporalExtent DAG ───────────────────→ Timeline
```
+
+Components ultimately consume Timeline plus absolute Instants or Windows. A domain projection
+publishes those values upstream; general component Surfaces do not accept Script objects or carry
+the projector.
diff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.md
index 2b012a92..8710ae00 100644
--- a/docs/quickstart/tracks.md
+++ b/docs/quickstart/tracks.md
@@ -4,15 +4,17 @@ description: Peer track components — captions, media, typography and authored
---
Every audiovisual contribution entering the final composition is a peer **Track**. Tracks are flat
-(no nesting), and visual z-order is determined by the `stack-order` property in SVS. This page
+(no nesting). Every visual occurrence publishes an absolute `z`: a domain family such as Fine
+Caption may own it in a reusable Recipe, while base Visual Clips and Fine Text write it directly. This page
covers Caption, Media, Typography and Audio Track authoring.
## Caption system
-Caption uses a Script-owned document and a replaceable Style family:
+Caption uses a source-neutral document produced by Script and a replaceable Style family:
```text
-Script CaptionDocument + Timeline → complete timed Cues → Use presentation
+Script → CaptionDocument + NarrativeCaptionBinding
+Binding + NarrativeProjection → CaptionTiming → Use presentation
```
```svml
@@ -117,37 +119,43 @@ CJK dialogue can be written directly. For a display-only emoji that still follow
author the correspondence explicitly, such as `<🌐 | globe>`; the system will not invent a spoken
word for a bare symbol.
-### caption-fine:Track
+### caption-fine:Caption
Caption content comes from Script and Timeline. Uses choose presentation in time; later Uses replace earlier treatments inside their windows, including Hidden.
```svml
<caption:Hidden id="hidden"/>
-<caption-fine:Track id="captions" document={story.caption} timeline={speech.timeline}>
+<narrative-caption:Timing id="story-captions" document={story.caption}
+ binding={story.caption-binding} projection={story-time.projection}/>
+<caption-fine:Caption id="captions" document={story.caption} timing={story-captions}
+ timeline={speech.timeline} within={vertical.bounds}>
<caption-fine:Use style={primary-caption}/>
<caption-fine:Use role="ALICE" style={alice-caption}/>
<caption-fine:Use role="BOB" style={bob-caption}/>
- <caption-fine:Use during={story.selection.product-demo} style={dialogue-caption}/>
- <caption-fine:Use during={story.selection.private} style={hidden}/>
-</caption-fine:Track>
+ <caption-fine:Use during={product-demo-window} style={dialogue-caption}/>
+ <caption-fine:Use during={private-window} style={hidden}/>
+</caption-fine:Caption>
```
`||` organizes Cues. A window can start inside a Cue while retaining its complete text and original word timing. `role` filters the speaker independently of time. `at`/`for`, `until`/`for` and `start`/`end` use the same time language as other tracks.
-## Media overlays and B-roll
+## Visual Clips and B-roll
-B-roll is an editorial use of the generic Media Track, not a separate Track family. One Item can
+B-roll is an editorial use of a Visual Clip, not a separate Track family. One Clip can
place an image, generated video, prepared timed medium or compositable Surface at a semantic or
absolute window.
```svml
-<import as="media-track" from="@hypit/media-track@1"/>
+<import as="visual" from="@hypit/visual-track@1"/>
+<import as="time" from="@hypit/timeline-author@1"/>
<import as="wording" from="@hypit/text@1"/>
+<time:Clock id="clock" frame-rate="30"/>
```
-### media-track:Track and media-track:Item
+### visual:Track and visual:Clip
-Placement is an explicit Spatial Frame edge; appearance and motion remain reusable SVS values.
+Placement is an explicit Spatial Frame edge. Fit, source-time mapping and stack order belong directly
+to the occurrence; reusable pixel treatment and typed Motion remain optional values.
```svml
<wording:Value id="product-direction">
@@ -160,29 +168,42 @@ Placement is an explicit Spatial Frame edge; appearance and motion remain reusab
<seedance:Reference image={product-reference} person-reference="false"/>
</seedance:ReferenceVideo>
-<space:Frame id="product-frame" within={vertical}
+<space:Frame id="product-frame" within={vertical.bounds}
left="8%" top="20%" right="92%" bottom="68%"/>
<pipeline:Normalize id="product-media" source={product-motion.video}
- video="primary-moving" audio="none" span-authority="video" frame-rate="30"/>
-
-<media-track:Track id="product-broll" timeline={speech.timeline} canvas={vertical}>
- <media-track:Item media={product-media.media} frame={product-frame}
- during={story.selection.product-demo}
- appearance={recipes.media.product}
- motion={recipes.motion.product}/>
-</media-track:Track>
+ video="primary-moving" audio="none" span-authority="video" clock={clock}/>
+
+<visual:Motion id="product-motion-in">
+ <visual:Pose at="start" y="80" opacity="0" easing="ease-out"/>
+ <visual:Pose at="8f" y="0" opacity="1"/>
+ <visual:Pose at="end" y="0" opacity="1"/>
+</visual:Motion>
+
+<visual:Track id="product-broll" timeline={speech.timeline}>
+ <visual:Clip media={product-media.media} frame={product-frame}
+ during={story-time.product-demo} z="40" fit="contain"
+ treatment={recipes.visual.product} motion={product-motion-in}>
+ <visual:Map/>
+ </visual:Clip>
+</visual:Track>
```
`left`, `top`, `right` and `bottom` are edge coordinates inside the parent Frame; `right` and
`bottom` are not CSS-style margins. A Frame covering the middle 84% of the canvas horizontally is
`left="8%" right="92%"`, and `right="8%"` would place its right edge to the left of its left edge,
-which is rejected. The Selection contributes semantic points; Media performs the package-owned
-window projection.
-The same Item model also covers full-canvas cutaways, split screens and corner overlays. Ordered
-child layers, source occupancy and explicit Sequences are available when one source is not enough.
-
-Every Item, Member or sample Layer declares exactly one visual input form:
+which is rejected. A Narrative projection may publish `story-time.product-demo` upstream; Visual Track
+only consumes the resulting Window.
+Fit is the common constructor for the Clip's source-to-picture `SpatialMap2D`; the resolved Program
+stores the map rather than a second content rectangle. When a component or source-local evidence
+already owns the exact affine relation, declare a `<space:Map>` and pass it through `mapping={...}`
+instead of all fit attributes. The Clip's `frame` still independently controls clipping and Frame
+treatment.
+The same Clip model also covers full-canvas cutaways, split screens and corner overlays. A public
+Clip has one source. Relationships spanning several sources or Clips belong to a component rather
+than a built-in Sequence grammar.
+
+Every direct Clip or sample Layer declares exactly one visual input form:
| Input | Value | Meaning |
|---|---|---|
@@ -196,26 +217,32 @@ to. `audio="none"` carries the picture alone, and `audio="default"` carries the
which `audio-gain` then scales. These forms are explicit so a generic Blob is never guessed to be an
image or a video.
-**Outputs:** `{product-broll.visual}` and, only when explicitly authored, `{product-broll.audio}`.
+**Outputs:** `{product-broll.program}` and `{product-broll.visual}`. Audio is always authored on an
+Audio Track; connecting synchronized media here never selects its audio member.
## Audio tracks
`@hypit/audio-track` places explicitly prepared audio on the same Timeline as the visual
-Tracks. An `Item` consumes `SynchronizedMedia`; normalize a declared or generated audio Blob first,
-then choose its exact program window and occupancy:
+Tracks. A `Clip` consumes `SynchronizedMedia`; normalize a declared or generated audio Blob first,
+then choose its exact program Window and source-time relation:
```svml
<import as="media" from="@hypit/media@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="audio" from="@hypit/audio-track@1"/>
+<import as="time" from="@hypit/timeline-author@1"/>
+<time:Clock id="clock" frame-rate="30"/>
<media:Audio id="music" src="./assets/music.wav"/>
<pipeline:Normalize id="music-media" source={music}
- video="none" audio="default" span-authority="audio" frame-rate="30"/>
+ video="none" audio="default" span-authority="audio" clock={clock}/>
<audio:Track id="music-bed" timeline={speech.timeline}>
- <audio:Item source={music-media.media} during="program"
- playback="loop-end" gain="0.28" fade-in="600ms" fade-out="800ms"/>
+ <audio:Clip source={music-media.media} during="timeline"
+ 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"/>
+ </audio:Clip>
</audio:Track>
```
@@ -223,14 +250,13 @@ then choose its exact program window and occupancy:
|---|---|---|
| `Track.id` | yes | Stable Audio Track identity |
| `Track.timeline` | yes | Timeline that defines the exact sample and frame domain |
-| `Item.source` | yes | Explicitly selected and normalized `SynchronizedMedia` |
+| `Clip.source` | yes | Explicitly selected and normalized `SynchronizedMedia` |
| `during`, `at`/`for`, or `start`/`end` | exactly one form | Whole-program, Selection, Moment, or explicit window |
-| `playback` | no | `once`, `once-end`, `loop`, `loop-end`, or bounded `stretch` |
-| `trim-start`, `trim-end` | no | Exact source trim |
-| `gain`, `fade-in`, `fade-out` | no | Explicit per-item mix values |
+| `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 |
The package performs no automatic extraction, normalization, ducking, or bus routing. Multiple
-Items in one Track and multiple peer Audio Tracks remain independent inputs to Film. The output is
+Clips in one Track and multiple peer Audio Tracks remain independent inputs to Film. The output is
`{music-bed.audio}`, an ordinary `AudioTrack`.
## Text overlays
@@ -238,79 +264,83 @@ Items in one Track and multiple peer Audio Tracks remain independent inputs to F
Static or timed text displayed on screen — titles, callouts, lower thirds.
```svml
-<import as="text" from="@hypit/typography-track@1"/>
+<import as="text" from="@hypit/text-fine@1"/>
<import as="wording" from="@hypit/text@1"/>
```
-### text:Track
+### text:Flow, text:Point and text:Path
-Container for text items.
+Fine text does not have an aggregate container. Each independently authored title, label or short
+piece of editorial copy is one occurrence and one ordinary VisualTrack contribution.
```svml
<space:Canvas id="vertical" width="1080" height="1920"/>
-<space:Frame id="title-frame" within={vertical}
+<space:Frame id="title-frame" within={vertical.bounds}
left="6%" top="6%" right="94%" bottom="16%"/>
<fonts:Stack id="title-font" family="inter" weight="900" style="normal"/>
<text:Style id="title-style" recipe={recipes.text.title} font={title-font}/>
-<text:Track id="titles" timeline={speech.timeline}>
- <text:Area id="title" placement={title-frame} style={title-style} during="program">
- EDIT MEANING, NOT TIMELINES
- </text:Area>
-</text:Track>
+<text:Flow id="title" timeline={speech.timeline} within={title-frame}
+ style={title-style} z="90" align="center" during="timeline">
+ EDIT MEANING, NOT TIMELINES
+</text:Flow>
```
| Attribute | Required | Description |
|---|---|---|
| `id` | yes | Unique identifier |
-| `semantic` | yes | Timeline from `time:Timeline` — also resolves Selection-based item timing |
-
-### text:Point, text:Area and text:Path
+| `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 |
+| `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 |
+| form layout | no | `Flow` alignment/wrapping, `Point` anchors or `Path` margins and direction, written only on the matching occurrence |
-Each item has one explicit placement form, one exact Style and one temporal projection. `Area`
-places flowing text inside a `SpatialFrame`:
+Each occurrence has one explicit placement form, one exact Style and one absolute time expression.
+`Flow` places flowing text inside a `SpatialFrame`:
```svml
-<text:Area id="meaning" placement={title-frame} style={title-style} during="program">
+<text:Flow id="meaning" timeline={speech.timeline} within={title-frame}
+ style={title-style} z="90" align="center" during="timeline">
MEANING
-</text:Area>
+</text:Flow>
```
| Attribute | Required | Description |
|---|---|---|
| `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 |
-| `during` | yes | `"program"` or a Selection reference; `at` and explicit `start`/`end` are also available |
-| `placement` | yes | `SpatialPoint`, `SpatialFrame` or `SpatialPath`, matching the item form |
+| timing | yes | `during="timeline"`, an absolute Window, or `at`/`for`, `until`/`for`, `start`/`end` |
+| 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 |
-The `during` attribute accepts the literal string `"program"` for the complete Timeline,
-or a Selection or Segment reference for semantic timing. The same temporal interface also accepts
-authored `start`/`end` windows and `at`/`for` events:
+`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
+does not know which domain produced it:
```svml
<text:Style id="callout-style" recipe={recipes.text.callout} font={title-font}/>
-<text:Track id="callout" timeline={speech.timeline}>
- <text:Area id="callout-copy" placement={callout-frame}
- style={callout-style} during={story.selection.callout}>
- EXACTLY THE RIGHT MOMENT
- </text:Area>
-</text:Track>
+<text:Flow id="callout-copy" timeline={speech.timeline} within={callout-frame}
+ style={callout-style} z="90" during={program.callout}>
+ EXACTLY THE RIGHT MOMENT
+</text:Flow>
```
Graph-produced copy remains visible as an edge:
```svml
<wording:Value id="headline">EXACTLY THE RIGHT MOMENT</wording:Value>
-<text:Track id="callout" timeline={speech.timeline}>
- <text:Area id="callout-copy" content={headline}
- placement={callout-frame} style={callout-style} during="program"/>
-</text:Track>
+<text:Flow id="callout-copy" timeline={speech.timeline} content={headline}
+ within={callout-frame} style={callout-style} z="90" during="timeline"/>
```
The generic Text value supplies only characters. Typography still owns the item document wrapper,
placement, timing, style and motion. Use inline `P`/`Span`/`Break` when the author needs rich runs.
-**Output:** `{titles.track}` — a VisualTrack added to `film:Film`.
+Each occurrence publishes `{callout-copy.occurrence}` for sibling text tools and
+`{callout-copy.visual}` for `film:Film`. Several unrelated titles remain several explicit Film
+inputs; coordination between them belongs in a project component, not an accidental text collection.
## Ranking boards
@@ -336,13 +366,14 @@ family is refused by name.
| Attribute | Takes |
|---|---|
-| `semantic` | the Timeline the board is timed against |
+| `timeline` | the absolute Timeline the board is timed against |
+| `semantic` | the optional Narrative projection used by semantic timing expressions |
+| `within` | a `space:Frame` when the selected board has an independent reveal or explanation stage |
| `frame` | a `space:Frame` — the board's declared placement |
| `during` | the timing form declared by the selected component |
| `style` | the matching style record, and only that variant's |
| `appear-sound`, `move-sound` | optional Synchronized Media |
| `terminal` | the Moment where the completed board settles. `TopThree` only |
-| `canvas` | an optional `space:Canvas` declared by the selected component |
Use only the timing forms admitted by the selected package; do not infer a terminal or reveal model
from another component family.
@@ -363,12 +394,12 @@ Each variant takes its own, at least one, and ids must be unique within a board.
```svml
<ranking:ColumnStyle id="board-style" recipe={recipes.ranking.board} font={ui-font}/>
-<ranking:Column id="board" timeline={speech.timeline} canvas={vertical} frame={board-frame}
- during={story.selection.board} style={board-style}>
+<ranking:Column id="board" timeline={speech.timeline} within={vertical.bounds} frame={board-frame}
+ during={story-time.board} style={board-style}>
<ranking:ColumnItem id="row-regen" rank="1" label="ReGen" icon={icon-regen}
- during={story.selection.regen-reveal}/>
+ during={story-time.regen-reveal}/>
<ranking:ColumnItem id="row-chatgpt" rank="2" label="ChatGPT" icon={icon-chatgpt}
- during={story.selection.chatgpt-reveal}/>
+ during={story-time.chatgpt-reveal}/>
<ranking:ColumnItem id="row-remini" rank="3" preset="true" label="Remini" icon={icon-remini}/>
</ranking:Column>
```
@@ -379,19 +410,17 @@ AudioTrack; without one there is no audio output to add.
## Card decks
A deck holds cards in depth: one is in front, the others recede behind it, and each new card is dealt
-on a Moment. Where a Media Item places one shot in one Frame, a deck keeps a stack of them in the
+on a Moment. Where a Visual Clip places one shot in one Frame, a deck keeps a stack of them in the
same Frame and moves the whole stack.
```svml
-<import as="deck" from="@hypit/deck-track@1"/>
+<import as="deck" from="@hypit/depth-stack@1"/>
```
### deck:DepthStack
-`id`, `timeline`, `canvas`, `frame` and `appearance` are required. The same Timeline supplies authored
-times and any placed semantic anchors. `until` says
-what ends the deck: a Moment, a Selection or Segment boundary, or an authored time such as `8s`.
-With a Selection or Segment, `until-boundary="start" | "end"` chooses its edge; the default is `end`.
+`id`, `timeline`, `within`, `frame`, `appearance` and `until` are required. `until` accepts an
+absolute Instant, for example a Narrative-projected event or `8s`.
### deck:Card
@@ -401,7 +430,7 @@ A direct child of the stack, self-closing, at least one, and dealt in document o
|---|---|
| `source` | required — a still image, a Synchronized Medium, or a Compositable Surface |
| `extent` | required for a still image and refused for anything else |
-| `at` | required — the reveal event: a Moment or an authored time such as `2s` or `12f` |
+| `at` | required — an absolute reveal Instant or an authored time such as `2s` or `12f` |
| `appearance` | optional — its own Recipe, otherwise the stack's |
| `label` | optional — a `deck:Label` record |
@@ -411,15 +440,15 @@ A direct child of the stack, self-closing, at least one, and dealt in document o
give both and it is refused. `size`, `color`, `align`, `block` and `padding` are optional.
```svml
-<space:Frame id="deck-frame" within={vertical} left="44%" top="60%" right="98%" bottom="88%"/>
-<deck:DepthStack id="deck" timeline={speech.timeline} canvas={vertical}
- frame={deck-frame} appearance={recipes.deck.stack} until={story.moment.done}>
- <deck:Card id="card-spatial" source={icon-spatial} extent={square} at={story.moment.deal-one}/>
- <deck:Card id="card-type" source={icon-type} extent={square} at={story.moment.deal-two}/>
+<space:Frame id="deck-frame" within={vertical.bounds} left="44%" top="60%" right="98%" bottom="88%"/>
+<deck:DepthStack id="deck" timeline={speech.timeline} within={vertical.bounds}
+ frame={deck-frame} appearance={recipes.deck.stack} until={story-time.done}>
+ <deck:Card id="card-spatial" source={icon-spatial} extent={square} at={story-time.deal-one}/>
+ <deck:Card id="card-type" source={icon-type} extent={square} at={story-time.deal-two}/>
</deck:DepthStack>
```
-**Output:** `{deck.track}` — a VisualTrack, an ordinary peer of every other Track in the Film.
+**Output:** `{deck.visual}` — a VisualTrack, an ordinary peer of every other Track in the Film.
## Screen overlays
@@ -436,10 +465,10 @@ empty, each with a required `z` for stacking order and a window that is one of:
| Window | Written |
|---|---|
-| The whole programme | `during="program"` |
-| A Selection | `during={story.selection.x}` on an item whose Track has `timeline={speech.timeline}` |
-| A Moment, for a length | `at={story.moment.x} for="12f"` on an item whose Track has `timeline={speech.timeline}` |
-| An explicit span | `start="…" end="…"`, optionally against a `selection=` or `moment=` |
+| The whole programme | `during="timeline"` |
+| An already resolved Window | `during={story-time.overlay}` |
+| An absolute start and length | `from="2s" for="12f"` |
+| An explicit span | `from={story-time.start} until={story-time.end}` |
Lengths are `12f`, `250ms` or `1.5s`. A Selection
names one contiguous interval and a Moment names one point; author another item when an effect should
@@ -452,13 +481,13 @@ required attributes, such as `color` / `intensity` / `attack` / `hold` / `decay`
None have defaults: an effect states its whole shape or is refused.
```svml
-<screen:Track id="effects" timeline={speech.timeline} canvas={vertical}>
- <screen:Flash during={story.selection.overlay} z="80"
+<screen:Track id="effects" timeline={speech.timeline} within={vertical.bounds}>
+ <screen:Flash during={story-time.overlay} z="80"
color="#ffffff" intensity="0.6" attack="2" hold="2" decay="6"/>
</screen:Track>
```
-**Output:** `{effects.track}` — a VisualTrack.
+**Output:** `{effects.visual}` — a VisualTrack.
## Comment stickers
@@ -482,15 +511,15 @@ image, and there is no `z`: stacking order comes from the recipe's `stack-order`
```svml
<comment:Style id="social" recipe={recipes.comment} font={ui-font}/>
-<comment:Track id="comments" canvas={vertical} timeline={speech.timeline}>
+<comment:Track id="comments" timeline={speech.timeline}>
<comment:Sticker id="one" frame={comment-frame} style={social} avatar={viewer-avatar}
- author="@viewer" meta="Featured" during={story.selection.reaction}>
+ author="@viewer" meta="Featured" during={story-time.reaction}>
Wait, it pinned the caption to the word, not the second.
</comment:Sticker>
</comment:Track>
```
-**Output:** `{comments.track}` — a VisualTrack.
+**Output:** `{comments.visual}` — a VisualTrack.
## Combination example
@@ -502,10 +531,13 @@ All four track families together in one source file:
<import as="fonts" from="@hypit/fonts-open@1"/>
<import as="media" from="@hypit/media@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
-<import as="media-track" from="@hypit/media-track@1"/>
-<import as="text" from="@hypit/typography-track@1"/>
+<import as="visual" from="@hypit/visual-track@1"/>
+<import as="text" from="@hypit/text-fine@1"/>
<import as="audio" from="@hypit/audio-track@1"/>
<import as="space" from="@hypit/spatial@1"/>
+<import as="time" from="@hypit/timeline-author@1"/>
+
+<time:Clock id="clock" frame-rate="30"/>
<!-- Captions: primary style for all text -->
<fonts:Stack id="caption-font" family="inter" weight="700" style="normal"/>
@@ -513,59 +545,57 @@ All four track families together in one source file:
<caption-fine:Style id="base-caption" recipe={recipes.caption.base} font={caption-font}/>
<caption:Hidden id="hidden"/>
-<caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline}>
+<caption-fine:Caption id="captions" document={story.caption} timing={story-captions}
+ timeline={speech.timeline} within={vertical.bounds}>
<caption-fine:Use style={base-caption}/>
- </caption-fine:Track>
+ </caption-fine:Caption>
<!-- Shared placement is an explicit edge, separate from Text appearance. -->
<space:Canvas id="vertical" width="1080" height="1920"/>
-<space:Frame id="title-frame" within={vertical}
+
+<space:Frame id="title-frame" within={vertical.bounds}
left="6%" top="6%" right="94%" bottom="16%"/>
-<space:Frame id="card-frame" within={vertical}
+
+<space:Frame id="card-frame" within={vertical.bounds}
left="10%" top="20%" right="90%" bottom="70%"/>
-<!-- Media: one ordinary Item used editorially as B-roll -->
+<!-- Media: one ordinary Clip used editorially as B-roll -->
<pipeline:Normalize id="card-media" source={motion.video}
- video="primary-moving" audio="none" span-authority="video" frame-rate="30"/>
-<media-track:Track id="cards" timeline={speech.timeline} canvas={vertical}>
- <media-track:Item media={card-media.media} frame={card-frame}
- during={story.selection.demo} appearance={recipes.media.card} motion={recipes.motion.card}/>
-</media-track:Track>
+ video="primary-moving" audio="none" span-authority="video" clock={clock}/>
+<visual:Track id="cards" timeline={speech.timeline}>
+ <visual:Clip media={card-media.media} frame={card-frame}
+ during={story-time.demo} z="40" fit="cover" treatment={recipes.visual.card}/>
+</visual:Track>
<!-- Text: persistent title overlay -->
<text:Style id="title-style" recipe={recipes.text.title} font={title-font}/>
-<text:Track id="titles" timeline={speech.timeline}>
- <text:Area id="meaning" placement={title-frame} style={title-style} during="program">
- MEANING
- </text:Area>
-</text:Track>
+<text:Flow id="meaning" timeline={speech.timeline} within={title-frame}
+ style={title-style} z="90" align="center" during="timeline">
+ MEANING
+</text:Flow>
<!-- Audio: normalize one declared source, then place it for the complete program -->
<media:Audio id="music" src="./assets/music.wav"/>
<pipeline:Normalize id="music-media" source={music}
- video="none" audio="default" span-authority="audio" frame-rate="30"/>
+ video="none" audio="default" span-authority="audio" clock={clock}/>
<audio:Track id="music-bed" timeline={speech.timeline}>
- <audio:Item source={music-media.media} during="program"
- playback="loop-end" gain="0.28" fade-in="600ms" fade-out="800ms"/>
+ <audio:Clip source={music-media.media} during="timeline"
+ 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"/>
+ </audio:Clip>
</audio:Track>
<!-- All peer tracks feed into Film -->
-<import as="sound" from="@hypit/sound@1"/>
-<sound:Style id="voice-style"/>
-<sound:Track id="voice" timeline={speech.timeline}>
- <sound:Use style={voice-style}/>
-</sound:Track>
-
-<film:Film id="main" canvas={vertical} timeline={speech.timeline} appearance={recipes.film.vertical}>
- <film:Track source={performance.visual}/>
- <film:Track source={voice.audio}/>
+<film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline} appearance={recipes.film.vertical}>
+ <film:Track source={picture.visual}/>
+ <film:Track source={mix.audio}/>
<film:Track source={cards.visual}/>
- <film:Track source={captions.track}/>
- <film:Track source={titles.track}/>
+ <film:Track source={captions.visual}/>
+ <film:Track source={meaning.visual}/>
<film:Track source={music-bed.audio}/>
</film:Film>
```
-In this example, the Recipes place the performance picture at 10, media at 40, captions at 70 and
+In this example, the Recipes place the ordinary source picture at 10, Clips at 40, captions at 70 and
text at 90. Higher values paint on top; the author chooses these relationships for the composition.
diff --git a/docs/zh/guide/author-packages.md b/docs/zh/guide/author-packages.md
index 56090425..50dc99f6 100644
--- a/docs/zh/guide/author-packages.md
+++ b/docs/zh/guide/author-packages.md
@@ -3,7 +3,7 @@ title: 添加作者包
description: 制作项目组件、将其用于视频,并在有需要时分享。
---
-创建组件是制作视频的一部分。从场景需要的行为出发:哪些内容共同出现,哪些内容会变化,由什么事件驱动。普通素材呈现可以使用 Media Track;一个播放中的视频移到侧面、同时让出空间展示流程图,可以属于同一个项目组件,独立字幕继续分开。
+创建组件是制作视频的一部分。从场景需要的行为出发:哪些内容共同出现,哪些内容会变化,由什么事件驱动。普通素材呈现可以使用 Visual Track;一个播放中的视频移到侧面、同时让出空间展示流程图,可以属于同一个项目组件,独立字幕继续分开。
## 从完整的包开始
diff --git a/docs/zh/guide/packages.md b/docs/zh/guide/packages.md
index 3d3d7191..55d8810a 100644
--- a/docs/zh/guide/packages.md
+++ b/docs/zh/guide/packages.md
@@ -20,7 +20,7 @@ Hypit 把视频需要什么,与哪些代码和服务完成它,分别表达
## 组件随作品需要组织
-在适合提取秩序的地方组织空间。Media Track 可以呈现普通视频或图片;项目组件可以把移动的视频视口、标签和流程图作为一个场景协调起来。独立字幕或叠加层仍可分开。共享行为决定哪些内容属于同一个组件。
+在适合提取秩序的地方组织空间。Visual Track 可以呈现普通视频或图片;项目组件可以把移动的视频视口、标签和流程图作为一个场景协调起来。独立字幕或叠加层仍可分开。共享行为决定哪些内容属于同一个组件。
对于说话视频,Script Selection 与 Moment 让组件跟随表演的含义;作者主导节奏的动画,则可以在声明的时钟上使用秒或帧。[Film 与渲染](../quickstart/composition.md) 介绍这些贡献如何组成作品。
diff --git a/docs/zh/guide/studio-temporal-windows.md b/docs/zh/guide/studio-temporal-windows.md
index 3e348ceb..ce379d55 100644
--- a/docs/zh/guide/studio-temporal-windows.md
+++ b/docs/zh/guide/studio-temporal-windows.md
@@ -1,61 +1,47 @@
---
title: Studio 中的时间编辑
-description: 区分跟随语义、使用时钟,以及时间编辑实际改变的对象。
+description: 修改产生绝对 Instant 或 Window 的声明。
---
-时间表达记录作者的选择。讲解画面可以跟随一句话,闪光可以响应答案,独立动画可以使用影片时钟。
-Studio 修改的是该写法所表达的选择。
+组件消费绝对 Instant 与 Window。Studio 沿图找到这个值的生产者,修改那一处声明;它不会
+要求每个视觉、音频、字幕或文字组件都理解值来自哪个领域。
-[Script](../quickstart/script.md) 用 Selection 和 Moment 为语义范围与事件命名。
-Timeline 放置准备好的表演;组件通过这些身份或时钟位置获得 Instant、Window。
-无声动画使用同一种 Timeline,由作者声明完整时长。
-
-## 选择需要编辑的关系
+## 绝对时间声明
| 作者写法 | 移动时改变什么 | 裁剪时改变什么 |
| --- | --- | --- |
-| `during={story.selection.proof}` | 两个共享 Script 锚点移动相同数量的语义停靠点;时长可能变化 | 对应的 Selection 边界 |
-| 事件的 `at={story.moment.reveal}` | 共享 Moment 锚点 | 该写法没有声明持续时间 |
-| 事件的 `at={story.selection.proof} boundary="start"` | 仅 Selection 的起点锚点 | 该写法没有声明持续时间 |
-| `at={story.moment.reveal} for="8f"` | Moment;持续时间保持八帧 | 从尾端改变持续时间;Moment 保持不变 |
-| `until={story.moment.reveal} for="8f"` | Moment;持续时间保持八帧 | 从首端改变持续时间;Moment 保持不变 |
-| `at="2s" for="8f"` | 作者指定的时钟位置 | 从尾端改变持续时间 |
-| `instant="moment.cue + 2f" moment={story.moment.reveal}` | 局部偏移;Moment 保持不变 | 该写法没有声明持续时间 |
-| `start="…" end="…"` | 两个端点表达式移动相同帧数 | 仅对应端点的表达式 |
-| `during={story.segment.opening}` 或 `during="program"` | 跟随结构范围,不提供时间线拖动 | 不提供时间线裁剪 |
-
-消费组件决定需要 Instant 还是 Window,以及支持哪些写法。事件跟随 Selection 终点时使用
-`boundary="end"`,同样只修改选定边界。
-
-## 分清共享语义与局部偏移
-
-移动 `at={story.moment.reveal}` 会在 Script 中移动 Moment,所有使用它的组件随后一起跟随。
-使用相同 Moment 的 `instant="moment.cue"` 则暴露一个初始为零的局部偏移;移动它不会改写共享事件。
+| `from="2s" for="8f"` | 改 `from`,时长仍为八帧 | `from` 或 `for` |
+| `until="3s" for="8f"` | 改 `until`,时长仍为八帧 | `for` 或 `until` |
+| `from="1s" until="3s"` | 两个端点移动相同帧数 | 被选择的端点 |
+| `during="timeline"` | 不提供局部写回 | 不提供局部写回 |
+| `during={named-window}` | 修改具名值的生产者 | 修改具名值的生产者 |
-需要有意提前或延后时,写 `instant="moment.cue + 2f"` 并绑定 `moment={story.moment.reveal}`。
-计算表达式不写进 `{story.moment.reveal}` 这样的图值引用中。
+Instant 引用遵循同样规则:`at={claim}` 跟随产生 `claim` 的声明;`at="2s"` 修改自己的时钟值。
-事件与持续时间是两个独立决定。`at/for` 只在尾端提供时长裁剪,`until/for` 只在首端提供时长裁剪。
-另一端不会提供一个同时移动共享事件、再补偿时长的隐藏操作。
+## 领域产生的时间值
-## 保留原文与所选边界
+语义时间先投影,再交给组件:
-词首、词尾和结构边界是不同的语义锚点。停顿可以属于前一句,也可以属于后一句。
-拖动沿不同帧位置上的语义停靠点进行;多个锚点重合时,支持该编辑的 Inspector 可以选择精确身份。
-Take 交叠或重排时,Script 顺序可以与实际时间顺序不同。
+```svml
+<semantic:Projection id="story-time" narrative={story} timeline={film.timeline}>
+ <semantic:Map alignment={speech.alignment} domain={speech-media.domain} window={film.speech}/>
+ <semantic:Window id="proof" selection={story.selection.proof}/>
+ <semantic:Instant id="reveal" moment={story.moment.reveal}/>
+</semantic:Projection>
-移动标记保留无关原文、空格、标点、发音和词属性。字幕 Cue 保留来自 Script 的内容及实测词时间。
-在 Script 中修改文案或 Cue 边界,通过 Caption Style 与带时间范围的 Use 修改呈现。
+<visual:Clip during={story-time.proof} .../>
+<deck:Card at={story-time.reveal} .../>
+```
-未编辑的表达式保留原单位:`2s` 在帧率变化后仍是两秒,`60f` 则保持六十帧。
-拖动改变的时钟位置或偏移以当前帧率下的整数帧写回。
+Narrative 投影声明保留 Companion 写回 Selection 或 Moment 所需的来源关系。修改这一声明后,
+所有消费者通过普通重新编译一起更新;消费者自身只收到完成的绝对时间值。未来的节拍投影
+可以提供完全不同的编辑规则,同时发布相同的 Temporal 类型。
-## 编辑项目组件
+如果生产者没有声明逆操作,解析出的值仍然可以正常使用,但 Studio 不会猜测写回目标。
+这使共享语义、局部时钟值和组件行为彼此分离。
-组件的 Companion 把画面实体连接到实际作者输入和已投影的时间。时间形式决定编辑对象,
-组件名称或偶然相同的帧位置不能代替该关系。Script Companion 拥有源码观察和标记移动;
-增加新组件不需要让 Studio 再学习一种 Script 解释方式。
+未修改的表达保留原单位:帧率变化后 `2s` 仍是两秒,`60f` 仍是六十帧。修改后的时钟值
+按当前 Timeline 写在整数帧边界上。
[Studio](../quickstart/preview.md) 介绍编辑界面,[Companion 指南](./studio-companion-architecture.md)
-介绍如何公开实体和控件;包内的[时间编辑参考](https://github.com/hypit-ai/hypit/blob/main/packages/temporal-markup/EDITING.md)
-维护精确实现接口和支持的操作。
+介绍包自己拥有的实体与控件。
diff --git a/docs/zh/quickstart/composition.md b/docs/zh/quickstart/composition.md
index 2df82ed0..b7b08ed2 100644
--- a/docs/zh/quickstart/composition.md
+++ b/docs/zh/quickstart/composition.md
@@ -1,10 +1,10 @@
---
title: Film 与渲染
-description: 将 Track 组合为 Film 并渲染为视频。
+description: 装配并列的画面与声音贡献,再渲染所选节目区间。
---
-Film 是最终的组装阶段。它接收所有对等的 Track,对其进行验证,并生成一个
-Composition。然后渲染器将该 Composition 编译为 MP4 视频。
+Film 是普通作者组件。它把显式选择的 VisualTrack、AudioTrack 与一个 Canvas、一个 Timeline
+组合成 Composition。渲染器再把 Composition 变成视频。
```svml
<import as="space" from="@hypit/spatial@1"/>
@@ -12,292 +12,126 @@ Composition。然后渲染器将该 Composition 编译为 MP4 视频。
<import as="render" from="@hypit/render-hyperframes@1"/>
```
-## film:Film
-
-将选定的 VisualTrack 和 AudioTrack 组装为单一的 Composition。每份视觉贡献保留自己的
-定时呈现和绘制顺序;声音通过选定的 AudioTrack 加入。
+## 装配 Film
```svml
<space:Canvas id="vertical" width="1080" height="1920"/>
-<import as="sound" from="@hypit/sound@1"/>
-<sound:Style id="voice-style"/>
-<sound:Track id="voice" timeline={speech.timeline}>
- <sound:Use style={voice-style}/>
-</sound:Track>
-
-<film:Film id="main" canvas={vertical} timeline={speech.timeline} appearance={recipes.film.vertical}>
- <film:Track source={performance.visual}/>
- <film:Track source={voice.audio}/>
- <film:Track source={captions.track}/>
- <film:Track source={product-broll.visual}/>
- <film:Track source={titles.track}/>
+
+<film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline}
+ appearance={recipes.film.vertical}>
+ <film:Track source={picture.visual}/>
+ <film:Track source={mix.audio}/>
+ <film:Track source={cards.visual}/>
+ <film:Track source={captions.visual}/>
+ <film:Track source={meaning.visual}/>
</film:Film>
```
-| 属性 | 必填 | 说明 |
+| 属性 | 必填 | 含义 |
|---|---|---|
-| `id` | 是 | 唯一标识符 |
-| `canvas` | 是 | 与 Track 布局共享的显式 CanvasSpace |
-| `timeline` | 是 | 完整时间轴及其中的素材放置和语义锚点 |
-| `appearance` | 是 | SVS Film Recipe——画布清除颜色 |
-
-### film:Track
+| `id` | 是 | 公开 Composition 身份 |
+| `canvas` | 是 | 画面坐标系 |
+| `timeline` | 是 | 有限的绝对节目范围 |
+| `appearance` | 是 | Film Recipe,包括清屏颜色 |
-每个 `<film:Track>` 子元素向 Composition 添加一个 Track 来源:
+每个 `<film:Track>` 接受一个 VisualTrack 或 AudioTrack。Film 不会发现某个输出的“兄弟端口”。
+如果同一份规范化媒体要同时贡献画面和声音,就分别从它声明一个 Visual Clip 和一个
+Audio Clip,并在这里显式选择两边产出的 Track。
-| 属性 | 必填 | 说明 |
-|---|---|---|
-| `source` | 是 | 来自任何上游组件的 VisualTrack 或 AudioTrack |
-
-常见的 Track 来源:
+常见输出包括:
-| 来源 | 类型 | 来自 |
+| 来源 | 类型 | 角色 |
|---|---|---|
-| `{performance.visual}` | VisualTrack | `performance:Track`——已有表演的画面呈现 |
-| `{voice.audio}` | AudioTrack | `sound:Track`——已有声音的呈现 |
-| `{captions.track}` | VisualTrack | Caption 样式族 Track——定时字幕 |
-| `{cards.visual}` | VisualTrack | `media-track:Track`——Media 叠加层或 B-roll |
-| `{titles.track}` | VisualTrack | `text:Track`——文字叠加层 |
+| `{picture.visual}` | VisualTrack | Visual Track 放置的画面出现关系 |
+| `{mix.audio}` | AudioTrack | Audio Track 中的语音、音乐与效果 |
+| `{cards.visual}` | VisualTrack | 独立图片或视频 Clip |
+| `{captions.visual}` | VisualTrack | Caption 家族 |
+| `{scene.visual}` | VisualTrack | 项目组件 |
-### Track 堆叠
+公开输出是 `{main.composition}`。
-Film 收集对等的 Track。每个 Track 可以包含多个独立定时、独立排序的呈现,称为 Present。
-许多组件通过 Recipe 的 `stack-order` 暴露绘制顺序:较低的值在后面,较高的值在前面。
-调整 Film 子元素的书写顺序不会改变这一绘制顺序。
+## 画面顺序属于 Present
-典型的堆叠顺序:
+Film 子项负责选择贡献,并不通过书写顺序定义画面堆叠。每个视觉组件发布带绝对 `z` 的
+定时 Present,通常由 Recipe 中的 `stack-order` 声明。数值小的先绘制;相同数值依次采用
+稳定的 Track 身份、Track 内 Present `order` 和 Present 身份。相对绘制关系确有意义时,作者
+应声明不同数值。
-| stack-order | 内容 |
-|---|---|
-| 10 | 示例口播视觉(作者显式选择,不是内置默认值) |
-| 40 | Media 叠加层 |
-| 70 | 字幕 |
-| 90 | 文字叠加层 |
+```svs
+film.vertical { background: #09090B; }
+media.speaker { stack-order: 10; fit: cover; }
+media.card { stack-order: 40; fit: contain; }
+caption.base { stack-order: 70; }
+/* Fine Text 在 Flow、Point 或 Path occurrence 上直接写 z="90"。 */
+```
-不同组件的 Present 可以交错排列。每个 Present 内部又拥有自己的元素树:多个视频、文字
-和图形可以共享布局、遮罩或协同运动。项目组件可以用 HTML/CSS 浏览器程序实现这样的场景,
-独立字幕或覆盖画面仍可以作为对等贡献。根据共同的表现关系分组,尺寸和素材类型不决定边界。
+不同 Track 的 Present 可以交错。若多张画面、图形与文字共享布局或运动,一个 Present
+也可以拥有内部元素树或浏览器程序。共享行为的内容放在一起;仍可独立使用的贡献保持并列。
-**输出:** `{main.composition}`——完整的 Composition,传递给渲染器。
+## 渲染完整视频
-## render:Video
+```svml
+<render:Video id="final"
+ composition={main.composition} timeline={speech.timeline}/>
+```
-通过 HyperFrames 渲染器将 Composition 编译为最终视频。
+渲染器编译视觉贡献、捕获所需帧、渲染 AudioTrack,并复用封装为交付文件。
+`{final.video}` 是普通 Resource-backed `BlobArtifact`,通常也是 Run Target。
```svml
-<render:Video id="final" composition={main.composition} timeline={speech.timeline}/>
+<?svml using="@hypit/run-markup@1"?>
+<svrun version="1">
+ <author source="./main.svml"/>
+ <target output="final.video"/>
+</svrun>
```
-| 属性 | 必填 | 说明 |
-|---|---|---|
-| `id` | 是 | 唯一标识符 |
-| `composition` | 是 | 来自 `film:Film` 的 Composition |
-| `timeline` | 是 | 完整时间轴及其中的素材放置和语义锚点 |
-
-渲染器:
+## 渲染帧区间
-1. 将 Composition 编译为 `HyperframesDocument`——每一帧的 HTML 表示
-2. 通过 Chrome/Chromium 渲染每一帧
-3. 将帧序列编码为视频
-4. 混合音频 Track
-5. 将视频和音频混合封装为最终的 MP4
+```svml
+<render:Video id="detail" composition={main.composition} timeline={speech.timeline}
+ start-frame="240" end-frame-exclusive="360"/>
+```
-**输出:** `{final.video}`——以普通内容寻址 `BlobArtifact` 表示的最终视频。这是最常见的
-Build Target,也可以直接接到媒体裁切、音频/帧提取或模型参考输入等后续 Blob 消费者。
+边界使用原 Timeline 的半开区间。30 fps 时,这个例子渲染第 8–12 秒。即使输出片段从零
+开始,动画和媒体采样仍保留原节目位置。区间渲染只限制最终捕获与编码;上游工作仍由 Run
+选择的图决定,因此应显式复用已接受的媒体与对齐输出。
## 完全由组件绘制的影片
-对于口播作品,Script 的 Selection 和 Moment 保留话语与呈现之间的关系。聊天动画或图解
-也可以自行安排阅读节奏:声明影片时钟,让场景组件、Film 和 Render 使用它。
+Timeline 不要求语音或媒体:
```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"/>
-<!-- scene.track 由使用同一时钟的组件产生。 -->
-<film:Film id="main" canvas={canvas} timeline={animation.timeline} appearance={recipes.film.main}>
- <film:Track source={scene.track}/>
-</film:Film>
-<render:Video id="final" composition={main.composition} timeline={animation.timeline}/>
-```
-场景事件可以采用作者指定的秒数或帧数。在口播编排中,同一种表现也可以跟随投影后的 Script
-事件。组件直接绘制画面,声明时长无需背景图片或静音表演;未选择 AudioTrack 时,交付视频无声。
+<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."/>
+</chat:Scene>
-## 完整的管线流程
-
-从 Script 到渲染视频的完整数据流。下面的 Source 是删节示意;可运行的完整项目见
-`examples/podcast/`,本节末尾的命令针对该项目。
-
-### Author Source (`main.svml`)
-
-```svml
-<?svml using="@hypit/markup@1"?>
-
-<svml>
- <import from="@hypit/script@1"/>
- <import as="wording" from="@hypit/text@1"/>
- <import as="gpt" from="@hypit/gpt-image@1"/>
- <import as="seedance" from="@hypit/seedance@1"/>
- <import as="pipeline" from="@hypit/media-pipeline@1"/>
- <import as="time" from="@hypit/timeline-author@1"/>
- <import as="whisperx" from="@hypit/whisperx@1"/>
- <import as="caption" from="@hypit/caption@1"/>
- <import as="caption-fine" from="@hypit/caption-fine@1"/>
- <import as="fonts" from="@hypit/fonts-open@1"/>
- <import as="media-track" from="@hypit/media-track@1"/>
- <import as="performance" from="@hypit/performance@1"/>
- <import as="text" from="@hypit/typography-track@1"/>
- <import as="space" from="@hypit/spatial@1"/>
- <import as="program" from="@hypit/program-space@1"/>
- <import as="film" from="@hypit/film@1"/>
- <import as="render" from="@hypit/render-hyperframes@1"/>
- <import as="recipes" source="./recipes.svs"/>
-
- <!-- 1. Script: the semantic truth -->
- <script id="story">
- <opening><HOST>Meaning @{demo}becomes the source.@{/demo}</opening>
- </script>
-
- <!-- 2. Generation: Seedance talking head + standalone video -->
- <wording:Value id="direction">
- Locked medium close-up in a quiet daylight studio. Spoken dialogue — say exactly: Meaning becomes the source.
- </wording:Value>
- <wording:Value id="scene-look">
- A photograph with the texture of real iPhone footage. Generate a vertical seated medium
- close-up, as one frame cut out of video actually shot on an iPhone: genuinely real rather than
- glossy, carrying the texture of video and not of a posed photograph. The background stays clearly
- visible, with no depth-of-field blur. Skin texture is fine and real, the light is natural, and no
- part of the picture is broken. One presenter at a desk in a quiet daylight studio.
- </wording:Value>
- <gpt:Image id="studio-scene" prompt={scene-look} aspect-ratio="9:16" resolution="2K"/>
- <seedance:ReferenceVideo id="take" model="mini"
- prompt={direction} duration="5" generate-audio="true">
- <seedance:Reference image={studio-scene.image} person-reference="true"/>
- </seedance:ReferenceVideo>
- <seedance:ReferenceVideo id="motion" model="mini"
- prompt={direction} duration="5">
- <seedance:Reference image={studio-scene.image} person-reference="true"/>
- </seedance:ReferenceVideo>
-
- <space:Canvas id="vertical" width="1080" height="1920"/>
- <program:Clock id="clock" frame-rate="30"/>
- <space:Frame id="speech-frame" within={vertical}
- left="0%" top="0%" right="100%" bottom="100%"/>
- <space:Frame id="title-frame" within={vertical}
- left="6%" top="6%" right="94%" bottom="16%"/>
- <space:Frame id="card-frame" within={vertical}
- left="10%" top="20%" right="90%" bottom="70%"/>
-
- <!-- 3. Timing:先归一化并对齐 Segment,再装配 -->
- <pipeline:Normalize id="take-media" source={take.video}
- video="primary-moving" audio="default" span-authority="video" clock={clock}/>
- <pipeline:Normalize id="motion-media" source={motion.video}
- video="primary-moving" audio="none" span-authority="video" clock={clock}/>
- <whisperx:SemanticTake id="opening-semantic" narrative={story}
- segment={story.segment.opening} media={take-media.media} language="en"/>
- <time:Timeline id="speech" clock={clock}>
- <time:Take source={opening-semantic.take}/>
- </time:Timeline>
-<performance:Style id="performance-style" frame={speech-frame} appearance={recipes.media.performance}/>
- <performance:Track id="performance" timeline={speech.timeline} canvas={vertical}>
- <performance:Use style={performance-style} during="program"/>
- </performance:Track>
-
- <!-- 4. Tracks: captions, Media, text -->
- <fonts:Stack id="caption-font" family="inter" weight="700" style="normal"/>
- <fonts:Stack id="title-font" family="inter" weight="900" style="normal"/>
- <caption-fine:Style id="base-caption" recipe={recipes.caption.base} font={caption-font}/>
-
- <caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline}>
- <caption-fine:Use style={base-caption}/>
- </caption-fine:Track>
-
- <media-track:Track id="cards" timeline={speech.timeline} canvas={vertical}>
- <media-track:Item media={motion-media.media} during={story.selection.demo}
- frame={card-frame} appearance={recipes.media.card} motion={recipes.motion.card}/>
- </media-track:Track>
- <text:Style id="title-style" recipe={recipes.text.title} font={title-font}/>
- <text:Track id="titles" timeline={speech.timeline}>
- <text:Area id="meaning" placement={title-frame} style={title-style} during="program">
- MEANING
- </text:Area>
- </text:Track>
-
- <!-- 5. Film: compose all tracks -->
- <import as="sound" from="@hypit/sound@1"/>
-<sound:Style id="voice-style"/>
-<sound:Track id="voice" timeline={speech.timeline}>
- <sound:Use style={voice-style}/>
-</sound:Track>
-
-<film:Film id="main" canvas={vertical} timeline={speech.timeline}
- appearance={recipes.film.vertical}>
- <film:Track source={performance.visual}/>
- <film:Track source={voice.audio}/>
- <film:Track source={cards.visual}/>
- <film:Track source={captions.track}/>
- <film:Track source={titles.track}/>
- </film:Film>
-
- <!-- 6. Render: compile to MP4 -->
- <render:Video id="final" composition={main.composition}
- timeline={speech.timeline}/>
-</svml>
-```
-
-`right` 与 `bottom` 是绝对的边位置,不是内缩量。一个占父级中间 80% 的 Frame 写作 `left="10%" right="90%"`,而不是 `left="10%" right="10%"`——后者解出的宽度为零,会被拒绝。
-
-### 样式表 (`recipes.svs`)
-
-```svs
-<?svml using="@hypit/svs@1"?>
-
-<sheet version="1">
- film.vertical {
- background: #09090B;
- }
- media.performance { stack-order: 0; fit: cover; }
- media.card {
- stack-order: 40; fit: cover; playback: hold-start;
- frame-paint: #111116; clip: rounded; radius: 20;
- }
- motion.card {
- enter: slide; enter-frames: 4; enter-direction: up; enter-easing: ease-out;
- exit: fade; exit-frames: 4; exit-easing: ease-in;
- }
- caption.base {
- stack-order: 70; x: 0.08; y: 0.76; width: 0.84;
- size: 58; line-height: 1; align: center;
- fill: #FFFFFF; background: #09090BCC; padding: 16 24; radius: 18;
- }
- text.title {
- stack-order: 90;
- font: Inter; weight: 900; size: 64; align: center;
- fill: #FFFFFF; tracking: -1;
- }
-</sheet>
+<film:Film id="main" canvas={canvas.canvas} timeline={animation.timeline}
+ appearance={recipes.film.main}>
+ <film:Track source={conversation.visual}/>
+</film:Film>
+<render:Video id="final" composition={main.composition} timeline={animation.timeline}/>
```
-### Run Source (`build.svrun`)
+组件用普通绝对时间拥有自己的阅读节奏。没有选择 AudioTrack 时,结果是静音的。在语音作品
+中,同一组件也可以使用投影到 Timeline 上的语义 Moment 或 Selection。
-```svml
-<?svml using="@hypit/run-markup@1"?>
-
-<svrun version="1">
- <author source="./main.svml"/>
- <target output="final.video"/>
-</svrun>
-```
-
-### 编译与验证
+## 执行前检查
```bash
-hypit check examples/podcast/reference.svml
-
-hypit plan examples/podcast/reference.svrun
+hypit check main.svml
+hypit plan build.svrun
```
-`check` 编译 Author Graph——验证所有导入、类型和图的边,而不调用任何外部服务。`plan`
-还会额外编译 Run Source 并输出冻结的 BuildPlan,展示调度器将发出的每个 Operation。在花费资金之前请先检查计划。
+`check` 在不调用外部服务的情况下验证导入、类型和图边。`plan` 编译选定 Run 并显示将要
+请求的 Operations。付费执行前应检查该计划。
+
+[时间与装配](./timing.md)解释规范化、Timeline 构造、媒体放置与语义投影;
+[Tracks](./tracks.md)解释 Visual 和 Audio 的作者形式。
diff --git a/docs/zh/quickstart/images.md b/docs/zh/quickstart/images.md
index 9728af59..d069800a 100644
--- a/docs/zh/quickstart/images.md
+++ b/docs/zh/quickstart/images.md
@@ -3,7 +3,7 @@ title: 图片操作
description: 在图片流向生成器或 Track 之前,对它做合成、校正与抠图。
---
-有三个包接收一张图片、交还一张图片。它们都不产出 Track:每个输出都是一张可供下游引用的图片——作为 Seedance 的参考帧、作为 Media Item,或作为下一次操作的来源。
+有三个包接收一张图片、交还一张图片。它们都不产出 Track:每个输出都是一张可供下游引用的图片——作为 Seedance 的参考帧、作为 Visual Clip,或作为下一次操作的来源。
它们都需要 Endpoint。`image-compose` 与 `image-transform` 索取 raster 能力,由 `@hypit/provider-image-opencv-local` 在本机运行 OpenCV 来满足;`background-removal` 索取的是它自己声明的能力,由所选项目 Provider 实现。使用这些操作时,在 [Runtime Profile](../guide/runtime.md) 中选择支持它们的 Endpoint。
@@ -26,7 +26,7 @@ description: 在图片流向生成器或 Track 之前,对它做合成、校正
| `opacity` | 可选——0 到 1,默认 1 |
```svml
-<compose:Image id="card" canvas={portrait} background="#00000000">
+<compose:Image id="card" canvas={portrait.canvas} background="#00000000">
<compose:Layer source={background.image} frame={full} fit="cover"/>
<compose:Layer source={product.image} frame={product-frame} fit="contain"/>
</compose:Image>
@@ -84,7 +84,7 @@ description: 在图片流向生成器或 Track 之前,对它做合成、校正
<remove:Background id="cutout" source={portrait.image}/>
```
-**输出:** `{cutout.image}`——通常喂给一个 Media Item,好让出镜者叠在画面上,而不是待在一个方框里。
+**输出:** `{cutout.image}`——通常喂给一个 Visual Clip,好让出镜者叠在画面上,而不是待在一个方框里。
## 移动人物抠像
@@ -95,4 +95,4 @@ description: 在图片流向生成器或 Track 之前,对它做合成、校正
<matte:Portrait id="cutout" source={performance.video}/>
```
-将 `cutout.video` 归一化,准备进入时间线。如果它建立说话节目的语义骨架,再把准备好的媒体与 Script Segment 对齐,通过 Timeline assembly 装配。画面由 Media Track 或项目场景按选择的位置、绘制顺序呈现。作为 B-roll 时,归一化后的抠像可以直接进入 Media Track。抠像改变画面背景,具体角色由编排决定。
+将 `cutout.video` 归一化,得到同步媒体及其局部时间域。如果它承载说话语义,就在该局部时间域上与 Script Segment 对齐,再通过等长的 Timeline Window 投影对齐证据。然后把规范化后的抠像作为普通 Visual Clip 放置。抠像改变画面背景,具体角色由编排决定。
diff --git a/docs/zh/quickstart/run.md b/docs/zh/quickstart/run.md
index b6c2673f..a3765d41 100644
--- a/docs/zh/quickstart/run.md
+++ b/docs/zh/quickstart/run.md
@@ -171,7 +171,7 @@ Hypit 永远不会猜测两个名字代表同一份作者意图。每次执行 `
| `output` | 要满足的逻辑输出 |
| `candidate` | 由 `build-record`、`file`、`value` 或 Fragment 导出声明的 Candidate 标识符 |
-Planner 会同时读取完整 Author Graph 与 Run Graph:裁剪所选 Candidate 替代掉的默认 Operation,同时保留该 Candidate 自身仍然消费的 Author Output。这是一次新的 Build,而非旧 Build 的延续。复用生成视频时,归一化和语义准备仍在下游;复用已经准备好的 SemanticTake 时,也保留这些结果。字幕、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/script.md b/docs/zh/quickstart/script.md
index c64dca3c..2411218c 100644
--- a/docs/zh/quickstart/script.md
+++ b/docs/zh/quickstart/script.md
@@ -117,7 +117,7 @@ Cue 的切换。这同样适用于其他语言的短语或名字,例如 `<Git
右侧。明确或共享的口播都必须包含可说出的词;`<API|...>` 只有标点,无法建立时间对应,因此无效。
`||` 是 **Caption Cue Break** 语法,只能位于完整对齐单元之间,不能写进 Dual Text 或切开
-N:M 单元。字幕稍后才把 CaptionDocument 与 Timeline 汇合得到帧时间。
+N:M 单元。字幕稍后通过独立 NarrativeCaptionBinding 与 NarrativeProjection 得到绝对帧时间。
### 空格与拼写
@@ -143,7 +143,7 @@ N:M 单元。字幕稍后才把 CaptionDocument 与 Timeline 汇合得到帧时
### CaptionDocument 的组成
-`CaptionDocument` 是 Script 拥有的字幕真相,包含三种明确的语法对象:
+`CaptionDocument` 是 Caption 拥有、Script 可由同一源码生成的显示值,包含三种明确的语法对象:
- **Display Word(显示词)**:一个用于渲染的词面,包含应该显示的标点;
- **Alignment Unit(对齐单元)**:最小的显示-口播对应关系,Dual Text 的 N:M 映射也保持为一个单元;
diff --git a/docs/zh/quickstart/styles.md b/docs/zh/quickstart/styles.md
index d894a9b2..e7fa3584 100644
--- a/docs/zh/quickstart/styles.md
+++ b/docs/zh/quickstart/styles.md
@@ -56,7 +56,7 @@ film.vertical {
```svml
<space:Canvas id="vertical" width="1080" height="1920"/>
-<film:Film id="main" canvas={vertical} timeline={speech.timeline} appearance={recipes.film.vertical}>
+<film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline} appearance={recipes.film.vertical}>
```
## Caption Fine
@@ -136,23 +136,22 @@ caption.bob {
<caption-fine:Style id="default-caption" recipe={recipes.caption.dialogue} font={caption-font}/>
<caption-fine:Style id="alice-caption" recipe={recipes.caption.alice} font={caption-font}/>
<caption-fine:Style id="bob-caption" recipe={recipes.caption.bob} font={caption-font}/>
-<caption-fine:Track id="captions" document={story.caption} timeline={speech.timeline}>
+<caption-fine:Caption id="captions" document={story.caption} timing={story-captions}
+ timeline={speech.timeline} within={vertical.bounds}>
<caption-fine:Use style={default-caption}/>
<caption-fine:Use role="ALICE" style={alice-caption}/>
<caption-fine:Use role="BOB" style={bob-caption}/>
-</caption-fine:Track>
+</caption-fine:Caption>
```
-## Media Track
+## Visual Track Clip
-Media 将空间位置、框呈现与生命周期运动分开。`SpatialFrame` 负责位置和尺寸;外观 Recipe
-负责素材适配与框材质;可选的 motion Recipe 负责入场、持续和退场。
+Visual Clip 将空间、源时间、像素处理与局部运动分开。`SpatialFrame` 负责位置和尺寸;
+`z`、fit 与可选的源时间偏映射是这次出现的直接事实。处理 Recipe 只复用图像与 Frame 的
+绘制,而类型化 Motion 是仿射/透明度关键帧,不是封闭的效果名。
```svs
-media.product {
- stack-order: 40;
- fit: contain;
- playback: hold-start;
+visual.product {
frame-paint: #111116;
clip: rounded;
radius: 28;
@@ -162,51 +161,50 @@ media.product {
border-color: #FFFFFF20;
shadows: 0 10 24 0 #00000066;
}
-
-motion.product {
- enter: slide;
- enter-frames: 8;
- enter-direction: up;
- enter-easing: ease-out;
- exit: fade;
- exit-frames: 6;
- exit-easing: ease-in;
-}
```
| 属性 | 描述 |
|---|---|
-| `stack-order` | Z 轴层叠顺序 |
+| `z` | 直接的 Z 轴层叠顺序;重叠 Clip 不可静默共用 |
| `fit` | `contain`、`cover`、`fit-width`、`fit-height`、`native`、`scale-down` 或 `stretch` |
| `frame-x`、`frame-y` | 放置 Frame 内的对齐点 |
| `content-x`、`content-y` | 素材内部独立选择的焦点 |
-| `playback` | `once-start`、`hold-start`、`loop-end`、`stretch` 等有时长素材占用方式 |
+| `source-time` / `Map` | 含时素材坐标的可复用或内联偏映射 |
| `frame-paint` | 采样素材背后的纯色或渐变 Paint |
| `clip`、`radius`、`padding` | 框裁切与内缩 |
| `border-*`、`shadows` | 框自有的边框与有序阴影 |
-| `enter`、`exit` | 生命周期算子;帧数、缓动和方向使用独立属性 |
-| `sustain` | 零个或多个确定性局部运动,例如 `float 12 2 up` |
+| `motion` / `Pose` | Clip 局部时钟上的可选仿射与透明度状态 |
位置始终是一条显式图边:
```svml
-<space:Frame id="product-frame" within={vertical}
+<space:Frame id="product-frame" within={vertical.bounds}
left="8%" top="20%" right="92%" bottom="68%"/>
-<media-track:Item media={product-media.media}
- during={story.selection.demo} frame={product-frame}
- appearance={recipes.media.product} motion={recipes.motion.product}/>
+<visual:Motion id="product-in">
+ <visual:Pose at="start" y="80" opacity="0" easing="ease-out"/>
+ <visual:Pose at="8f" y="0" opacity="1"/>
+ <visual:Pose at="end" y="0" opacity="1"/>
+</visual:Motion>
+<visual:Clip media={product-media.media}
+ during={story-time.demo} frame={product-frame}
+ z="40" fit="contain"
+ treatment={recipes.visual.product} motion={product-in}>
+ <visual:Map/>
+</visual:Clip>
```
+如果行为要协调多个对象、改变结构或赋予素材新的视觉角色,就编写组件。Motion 是共享的
+数学底座,不是试图枚举未来所有效果的目录。
+
## 文本
-文本叠加层外观——排版与 Paint。位置由另一条 `SpatialFrame` 图边提供。
+细粒度文字 Style 只拥有可复用的排版与 Paint。几何、具体形式的布局和绝对 `z`
+由每次 occurrence 直接拥有,因为这些事实会随同一 Style 的不同使用而改变。
```svs
text.title {
- stack-order: 90;
weight: 900;
size: 64;
- align: center;
fill: #FFFFFF;
tracking: -1;
}
@@ -214,10 +212,8 @@ text.title {
| 属性 | 描述 |
|---|---|
-| `stack-order` | Z 轴层叠顺序 |
| `weight` | 字体粗细 |
| `size` | 字体大小(像素) |
-| `align` | 文本对齐方式 |
| `fill` | 文本颜色 |
| `tracking` | 字间距调整 |
@@ -226,9 +222,10 @@ text.title {
```svml
<fonts:Stack id="title-font" family="inter" weight="900" style="normal"/>
<text:Style id="title-style" recipe={recipes.text.title} font={title-font}/>
-<text:Area id="meaning" placement={title-frame} style={title-style} during="program">
+<text:Flow id="meaning" timeline={speech.timeline} within={title-frame}
+ style={title-style} z="90" align="center" during="timeline">
MEANING
-</text:Area>
+</text:Flow>
```
## Speaker Text Template
@@ -380,5 +377,5 @@ Caption Recipe 不再重复家族、字重或字形。CJK 与 Emoji 即使由多
<caption-fine:Style id="primary-caption" recipe={recipes.caption.primary} font={caption-font}/>
<space:Canvas id="vertical" width="720" height="1280"/>
-<film:Film id="main" canvas={vertical} timeline={speech.timeline} appearance={recipes.film.vertical}>
+<film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline} appearance={recipes.film.vertical}>
```
diff --git a/docs/zh/quickstart/timing.md b/docs/zh/quickstart/timing.md
index fe475607..63460ce2 100644
--- a/docs/zh/quickstart/timing.md
+++ b/docs/zh/quickstart/timing.md
@@ -1,136 +1,123 @@
---
-title: 时序与装配
-description: 逐 Take 归一化与语义对齐,然后装配为 Timeline。
+title: 时间与装配
+description: 先构造绝对节目时间,再显式放置媒体并按需投影语义时间。
---
-对于说话视频,`Timeline` 把作者的 Script 与实际表演联系起来,是字幕、随词语出现的图形和覆盖画面的自然时间来源。它按 Segment 粒度构建:
+Hypit 只有一条节目时间轴:`Timeline`。它只是 `{ id, frameRate, frameCount }`,不包含素材、
+单词、Track 或中央事件注册表。
-1. 把每个已接受的音视频 Take 归一化到同一个精确帧域;
-2. 将归一化媒体与对应的 Script Segment 对齐,得到自包含的 `SemanticTake`;
-3. 用 `time:Timeline` 按节目顺序装配这些 Semantic Take。
+对于语音作品,四类独立事实围绕这条绝对时间轴组合:
-每个 Take 在进入 Timeline assembly 之前就已经具有语义。画面由 Media Track 或项目组件呈现,与这里的语义和音频装配分别表达。
+1. 把已接受素材规范化为 `SynchronizedMedia` 与有限的局部时间域;
+2. 在该局部时间域上对齐 Script Segment,得到 `NarrativeAlignment`;
+3. 用具名 Instant、Window 与 Extent 构造一个包含必需 `end` 的 Timeline DAG;
+4. 把每个 Alignment 通过等长 Window 投影,并让普通媒体独立进入 Visual 与 Audio Source。
-纯视觉动画使用同一种 Timeline 声明:指定结束时间,不放入 Take,见 [纯组件绘制的影片](./composition.md)。其事件可以使用秒或帧;说话视频则可以用 Script Selection 和 Moment 驱动相同的视觉行为。
+这种分离很重要:移动一段内容不改变媒体和局部词时序;改变画面构图不改变声音;纯动效
+只需要 Timeline,不需要媒体或 Script。
```svml
-<import as="program" from="@hypit/program-space@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
+<import as="semantic" from="@hypit/narrative-temporal@1"/>
<import as="time" from="@hypit/timeline-author@1"/>
-<import as="media-track" from="@hypit/media-track@1"/>
- <import as="performance" from="@hypit/performance@1"/>
-<import as="space" from="@hypit/spatial@1"/>
-<import as="recipes" source="./recipes.svs"/>
+<import as="media" from="@hypit/media@1"/>
+<import as="visual" from="@hypit/visual-track@1"/>
+<import as="audio" from="@hypit/audio-track@1"/>
```
-## 逐 Take 归一化
+## 规范化局部媒体
-归一化把视频、音频、时长和帧率变成一个明确的 `SynchronizedMedia` 事实。同一条
-Timeline 内的所有 Take 共享作者显式声明的 Clock。
+Clock 固定最终 Timeline 与所有局部时间域共享的帧率:
```svml
-<program:Clock id="clock" frame-rate="30"/>
-
+<time:Clock id="clock" frame-rate="30"/>
<pipeline:Normalize id="opening-media" source={opening-video.video}
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
<pipeline:Normalize id="answer-media" source={answer-video.video}
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
```
-归一化不包含 Script 语义,也不负责转录;它只建立后续语义对齐可以信任的客观媒体事实。
-
-## 每个 Segment 产生一个 SemanticTake
+规范化只建立媒体事实,不包含 Script 含义或节目中的位置。
-`whisperx:SemanticTake` 测量一段归一化媒体,并把声学证据与唯一一个作者 Segment 对齐:
+## 在局部时间域上对齐语义
```svml
-<whisperx:SemanticTake id="opening-semantic" narrative={story}
- segment={story.segment.opening} media={opening-media.media} language="en"/>
-<whisperx:SemanticTake id="answer-semantic" narrative={story}
- segment={story.segment.answer} media={answer-media.media} language="en"/>
+<whisperx:Alignment id="opening-alignment" narrative={story}
+ segment={story.segment.opening} media={opening-media.media}
+ domain={opening-media.domain} language="en"/>
+<whisperx:Alignment id="answer-alignment" narrative={story}
+ segment={story.segment.answer} media={answer-media.media}
+ domain={answer-media.domain} language="en"/>
```
-含有台词的 Segment 必须显式填写 `language`,例如 `en`、`zh` 或 `ko`。使用所选
-WhisperX 服务支持的小写两字母或三字母语言代码。该值原样传递;Hypit 不会根据 Script
-文本或音频自动检测、分流语言。无台词的空 Segment 省略 `language`,直接使用归一化媒体边界。
-
-每个输出都自带归一化媒体、Segment 身份、每个作者词语的局部帧窗口以及该 Segment 的全部
-结构锚点:Segment 有两个锚点,每个词也有两个锚点。声学证据只是这一步的实现输入;下游
-组件看到的是完成后的 `SemanticTake`,而不是第二套 evidence 形状的时间结构。
+每个输出只是 `NarrativeAlignment`:在局部时间域上测得的 Segment 与单词边界。它不包含
+媒体,也不选择 Timeline 位置。没有 Token 的 Segment 省略 `language`,边界直接采用局部
+时间域边界,并且不发起声学请求。
-## 装配 Timeline
+## 构造绝对 Timeline
-`time:Timeline` 默认顺接已经准备好的 Take,也允许通过 `at` 自由放置,提供完整 Timeline。
-Performance 和 Sound 分别呈现其中的画面和声音:
+Timeline 声明是无环构造图。`end` 必填;每个具名 Instant 或 Window 都自然发布为普通图值:
```svml
-<space:Canvas id="vertical" width="1080" height="1920"/>
-<space:Frame id="speech-frame" within={vertical}
- left="0%" top="0%" right="100%" bottom="100%"/>
-
-<time:Timeline id="speech" clock={clock}>
- <time:Take source={opening-semantic.take}/>
- <time:Take source={answer-semantic.take}/>
+<time:Timeline id="speech" clock={clock} end="answer.end">
+ <time:Window id="opening" from="start" for={opening-media.extent}/>
+ <time:Window id="answer" from="opening.end" for={answer-media.extent}/>
</time:Timeline>
-<import as="sound" from="@hypit/sound@1"/>
-<sound:Style id="voice-style"/>
-<sound:Track id="voice" timeline={speech.timeline}>
- <sound:Use style={voice-style}/>
-</sound:Track>
-<performance:Style id="performance-style" frame={speech-frame} appearance={recipes.media.performance}/>
- <performance:Track id="performance" timeline={speech.timeline} canvas={vertical}>
- <performance:Use style={performance-style} during="program"/>
- </performance:Track>
```
-| 输出 | 类型 | 含义 |
-|---|---|---|
-| `{speech.timeline}` | Timeline | 全局语义与帧域真相 |
-| `{voice.audio}` | AudioTrack | Sound 对已有 Take 声音的呈现 |
+每个 `for={...extent}` 使用已经解析、但尚未定位的时长。因此,未知长度的生成语音可以在
+普通图求值中撑开 Timeline。`from="opening.end+2s"` 表示空隙,
+`from="opening.end-12f"` 表示重叠,`latest(a.end,b.end)` 可以合并并行分支。纯动效可直接
+声明 `<time:Timeline id="animation" clock={clock} end="8s"/>`。Timeline 不保留媒体或局部
+时间域身份。
-Performance 和 Sound 使用同一批素材及源位置。每个 Take 的全局位置由放置起点加局部位置得到。
-第一段省略 `at` 表示从零开始,后续省略则顺接上一段。`at="previous.end+2s"` 留出间隔,
-`at="previous.end-12f"` 表示交叠,也可以写绝对位置。Timeline 的 `end` 默认取所有 Take 的最晚终点;
-`end="content.end+2s"` 留出片尾,`end="30s"` 指定完整时长。位置须落在精确帧上,完整范围须容纳所有 Take。
-零 Take 的 Timeline 需要明确的正时长,空隔不生成占位素材。
+## 独立投影语义
-## 消费语义时间
+把每个 Alignment、完整局部时间域和等长绝对 Window 配对,投影语义证据:
-Selection、Moment 与完整 Segment 始终是 Script 中的作者身份。下游组件只接收一次
-Timeline,并在构建确定性 Track 时把这些身份投影成帧:
+```svml
+<semantic:Projection id="story-time" narrative={story} timeline={speech.timeline}>
+ <semantic:Map alignment={opening-alignment.alignment}
+ domain={opening-media.domain} window={speech.opening}/>
+ <semantic:Map alignment={answer-alignment.alignment}
+ domain={answer-media.domain} window={speech.answer}/>
+ <semantic:Window id="proof" selection={story.selection.proof}/>
+ <semantic:Instant id="claim" moment={story.moment.claim}/>
+</semantic:Projection>
+```
+
+显式请求的 `story-time.proof` 与 `story-time.claim` 是普通的绝对 Window 与 Instant。
+语义时间只是一种可选投影来源;
+直接秒数、帧数以及 Timeline 的具名绝对值同样是一等公民。
+
+## 呈现画面与声音
```svml
-<media-track:Track id="cards" timeline={speech.timeline} canvas={vertical}>
- <media-track:Item image={card.image} extent={card-extent}
- during={story.selection.demo} frame={card-frame}
- appearance={recipes.media.card} motion={recipes.motion.card}/>
-</media-track:Track>
-
-<caption-fine:Track id="captions"
- document={story.caption}
- timeline={speech.timeline}
->
- <caption-fine:Use style={primary-caption}/>
-</caption-fine:Track>
-
-<film:Film id="main" canvas={vertical}
- timeline={speech.timeline} appearance={recipes.film.vertical}>
- <film:Track source={performance.visual}/>
- <film:Track source={voice.audio}/>
- <film:Track source={cards.visual}/>
- <film:Track source={captions.track}/>
-</film:Film>
-
-<render:Video id="final"
- composition={main.composition} timeline={speech.timeline}/>
+<visual:Track id="picture" timeline={speech.timeline}>
+ <visual:Clip id="opening" media={opening-media.media} during={speech.opening}
+ frame={speech-frame} z="10" fit="cover"/>
+ <visual:Clip id="answer" media={answer-media.media} during={speech.answer}
+ frame={speech-frame} z="10" fit="cover"/>
+</visual:Track>
+
+<audio:Track id="mix" timeline={speech.timeline}>
+ <audio:Clip id="opening" source={opening-media.media} during={speech.opening}/>
+ <audio:Clip id="answer" source={answer-media.media} during={speech.answer}/>
+</audio:Track>
```
-整段使用 `during={story.segment.answer}`,作者范围使用 Selection,点事件使用 Moment,完整节目使用 `during="program"`。组件统一消费 `timeline={speech.timeline}`。
+不再存在独立的 Performance、Sound 或通用 Presentation 协议。Visual 与 Audio Clip 是
+平等的媒体出现关系。同一份规范化媒体可以同时供两边使用,但选择画面绝不会自动让声音
+进入成片。
```text
-prepared Takes → Timeline → Performance / project scene → visual ─┐
- ├→ Caption / semantic graphics → visual ┤
- └→ Sound → audio ───────────────────────┤
- Film
+SynchronizedMedia + Window ──────────────────────────────→ Visual / Audio occurrence
+
+NarrativeAlignment + LocalDomain + Window ──────────────→ 绝对 Instant / Window
+
+Instant / Window / TemporalExtent DAG ───────────────────→ Timeline
```
+
+组件最终只消费 Timeline 与绝对 Instant/Window。领域投影在上游发布这些值;通用组件的
+Surface 不接受 Script 对象,也不携带投影器。
diff --git a/docs/zh/quickstart/tracks.md b/docs/zh/quickstart/tracks.md
index 900264bf..a46ea865 100644
--- a/docs/zh/quickstart/tracks.md
+++ b/docs/zh/quickstart/tracks.md
@@ -3,8 +3,9 @@ title: 轨道
description: 对等 Track 组件——字幕、媒体、排版与作者声明的音频。
---
-每个进入最终合成的视听内容都是一个对等的 **Track**。Track 是扁平的(无嵌套);视觉层的
-z 轴顺序由 SVS 中的 `stack-order` 属性决定。本页介绍 Caption、Media、Typography 与 Audio
+每个进入最终合成的视听内容都是一个对等的 **Track**。Track 是扁平的(无嵌套)。每个视觉
+occurrence 都发布绝对 `z`:Fine Caption 等领域家族可以把它放在可复用 Recipe 中,基础
+Visual Clip 与 Fine Text 则直接声明。本页介绍 Caption、Media、Typography 与 Audio
Track 的作者语法。
## 字幕系统
@@ -12,7 +13,8 @@ Track 的作者语法。
字幕由 Script 产生的单一文档与可替换的样式族组成:
```text
-Script CaptionDocument + Timeline → 完整 Cue 定时 → Use 呈现
+Script → CaptionDocument + NarrativeCaptionBinding
+绑定 + NarrativeProjection → CaptionTiming → Use 呈现
```
```svml
@@ -73,35 +75,41 @@ Fine 是“统一文字流”字幕:同一 Cue 的每个 token 遵守同一 Re
CJK 口播可以直接书写。若一个只负责显示的 emoji 仍需跟随语音计时,应显式写出对应,例如 `<🌐 | globe>`;系统不会替裸符号虚构一个口播词。
-### caption-fine:Track
+### caption-fine:Caption
字幕内容来自 Script 和 Timeline;Use 决定某段时间的呈现方式。后声明的 Use 在窗口内覆盖前面的样式,隐藏也遵守这个规则。
```svml
<caption:Hidden id="hidden"/>
-<caption-fine:Track id="captions" document={story.caption} timeline={speech.timeline}>
+<narrative-caption:Timing id="story-captions" document={story.caption}
+ binding={story.caption-binding} projection={story-time.projection}/>
+<caption-fine:Caption id="captions" document={story.caption} timing={story-captions}
+ timeline={speech.timeline} within={vertical.bounds}>
<caption-fine:Use style={primary-caption}/>
<caption-fine:Use role="ALICE" style={alice-caption}/>
<caption-fine:Use role="BOB" style={bob-caption}/>
- <caption-fine:Use during={story.selection.product-demo} style={dialogue-caption}/>
- <caption-fine:Use during={story.selection.private} style={hidden}/>
-</caption-fine:Track>
+ <caption-fine:Use during={product-demo-window} style={dialogue-caption}/>
+ <caption-fine:Use during={private-window} style={hidden}/>
+</caption-fine:Caption>
```
`||` 决定 Cue 分组。窗口可以从 Cue 中间开始,完整文字和原来的逐词时间仍然保留。`role` 按说话人过滤内容,独立于时间窗口。也可以使用 `at`/`for`、`until`/`for` 或 `start`/`end`。
-## Media 叠加层与 B-roll
+## Visual Clip 与 B-roll
-B-roll 是通用 Media Track 的一种剪辑用途,不是独立 Track 家族。一个 Item 可以在语义或绝对窗口内放置图片、生成视频、已规范化含时素材或 Compositable Surface。
+B-roll 是 Visual Clip 的一种剪辑用途,不是独立 Track 家族。一个 Clip 可以在语义或绝对窗口内放置图片、生成视频、已规范化含时素材或 Compositable Surface。
```svml
-<import as="media-track" from="@hypit/media-track@1"/>
+<import as="visual" from="@hypit/visual-track@1"/>
+<import as="time" from="@hypit/timeline-author@1"/>
<import as="wording" from="@hypit/text@1"/>
+<time:Clock id="clock" frame-rate="30"/>
```
-### media-track:Track 与 media-track:Item
+### visual:Track 与 visual:Clip
-位置是一条显式 Spatial Frame 边,外观和运动则是可复用的 SVS 值:
+位置是一条显式 Spatial Frame 边。fit、源时间映射与层叠顺序直接属于这次出现;像素处理
+Recipe 与类型化 Motion 都只是可选的复用值:
```svml
<wording:Value id="product-direction">
@@ -114,23 +122,37 @@ B-roll 是通用 Media Track 的一种剪辑用途,不是独立 Track 家族
<seedance:Reference image={product-reference} person-reference="false"/>
</seedance:ReferenceVideo>
-<space:Frame id="product-frame" within={vertical}
+<space:Frame id="product-frame" within={vertical.bounds}
left="8%" top="20%" right="92%" bottom="68%"/>
<pipeline:Normalize id="product-media" source={product-motion.video}
- video="primary-moving" audio="none" span-authority="video" frame-rate="30"/>
-
-<media-track:Track id="product-broll" timeline={speech.timeline} canvas={vertical}>
- <media-track:Item media={product-media.media} frame={product-frame}
- during={story.selection.product-demo}
- appearance={recipes.media.product}
- motion={recipes.motion.product}/>
-</media-track:Track>
+ video="primary-moving" audio="none" span-authority="video" clock={clock}/>
+
+<visual:Motion id="product-motion-in">
+ <visual:Pose at="start" y="80" opacity="0" easing="ease-out"/>
+ <visual:Pose at="8f" y="0" opacity="1"/>
+ <visual:Pose at="end" y="0" opacity="1"/>
+</visual:Motion>
+
+<visual:Track id="product-broll" timeline={speech.timeline}>
+ <visual:Clip media={product-media.media} frame={product-frame}
+ during={story-time.product-demo} z="40" fit="contain"
+ treatment={recipes.visual.product} motion={product-motion-in}>
+ <visual:Map/>
+ </visual:Clip>
+</visual:Track>
```
-`left`、`top`、`right`、`bottom` 是父 Frame 内的边坐标;`right` 和 `bottom` 不是 CSS 式外边距。Selection 只贡献语义点;Media 包负责将这些点投影为窗口。同一个 Item 模型也能表达全屏切换、分屏和角落小窗。需要多个素材时,可以使用有序局部 Layer 或显式 Sequence。
+`left`、`top`、`right`、`bottom` 是父 Frame 内的边坐标;`right` 和 `bottom` 不是 CSS 式外边距。
+Narrative 投影可以在上游发布 `story-time.product-demo`;Visual Track 只消费完成的 Window。同一个
+fit 是构造 Clip 源局部平面到节目画面 `SpatialMap2D` 的常用入口;解析后的 Program 保存 Map,
+而不是另存一个“内容框”。当组件或源局部证据已经拥有精确仿射关系时,可以声明
+`<space:Map>`,并用 `mapping={...}` 代替全部 fit 属性。Clip 的 `frame` 仍独立负责裁剪和外框处理。
+同一个
+Clip 模型也能表达全屏切换、分屏和角落小窗。公开 Clip 只有一个来源;跨多个来源或
+多个 Clip 的关系属于组件,而不是基础 Track 内置的 Sequence 语法。
-每个 Item、Member 或采样 Layer 都必须且只能声明一种视觉输入形式:
+每个直接 Clip 或采样 Layer 都必须且只能声明一种视觉输入形式:
| 输入 | 值 | 含义 |
|---|---|---|
@@ -140,26 +162,31 @@ B-roll 是通用 Media Track 的一种剪辑用途,不是独立 Track 家族
生成或导入的视频 Blob 经 `<pipeline:Normalize>` 进入 Track:它检查该 Blob、选出其中的流并放到同一个帧域上,输出的 `.media` 即 `media=` 所连接的值。`audio="none"` 只取画面,`audio="default"` 取源自带的声音,再由 `audio-gain` 调节。输入名必须显式,是为了绝不靠猜测把一个通用 Blob 当成图片或视频。
-**输出:**`{product-broll.visual}`;只有作者显式选择了源音频或 SFX 时才会出现
-`{product-broll.audio}`。
+**输出:**`{product-broll.program}` 与 `{product-broll.visual}`。音频始终在 Audio Track
+中单独声明;这里连接 SynchronizedMedia 不会顺带选择它的音频成员。
## Audio Track
-`@hypit/audio-track` 把显式准备好的音频放进与视觉 Track 相同的 Timeline。`Item`
-消费 `SynchronizedMedia`;先规范化已声明或生成的音频 Blob,再选择精确节目窗口与占用方式:
+`@hypit/audio-track` 把显式准备好的音频放进与视觉 Track 相同的 Timeline。`Clip`
+消费 `SynchronizedMedia`;先规范化已声明或生成的音频 Blob,再选择精确节目窗口与源时间关系:
```svml
<import as="media" from="@hypit/media@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="audio" from="@hypit/audio-track@1"/>
+<import as="time" from="@hypit/timeline-author@1"/>
+<time:Clock id="clock" frame-rate="30"/>
<media:Audio id="music" src="./assets/music.wav"/>
<pipeline:Normalize id="music-media" source={music}
- video="none" audio="default" span-authority="audio" frame-rate="30"/>
+ video="none" audio="default" span-authority="audio" clock={clock}/>
<audio:Track id="music-bed" timeline={speech.timeline}>
- <audio:Item source={music-media.media} during="program"
- playback="loop-end" gain="0.28" fade-in="600ms" fade-out="800ms"/>
+ <audio:Clip source={music-media.media} during="timeline"
+ 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"/>
+ </audio:Clip>
</audio:Track>
```
@@ -167,13 +194,12 @@ B-roll 是通用 Media Track 的一种剪辑用途,不是独立 Track 家族
|---|---|---|
| `Track.id` | 是 | 稳定的 Audio Track 身份 |
| `Track.timeline` | 是 | 定义精确采样域与帧域的 Timeline |
-| `Item.source` | 是 | 显式选流并规范化后的 `SynchronizedMedia` |
+| `Clip.source` | 是 | 显式选流并规范化后的 `SynchronizedMedia` |
| `during`、`at`/`for` 或 `start`/`end` | 三种形式选一 | 全节目、Selection、Moment 或显式窗口 |
-| `playback` | 否 | `once`、`once-end`、`loop`、`loop-end` 或有界 `stretch` |
-| `trim-start`、`trim-end` | 否 | 精确源裁切 |
-| `gain`、`fade-in`、`fade-out` | 否 | 显式的单 Item 混音值 |
+| `source-time` 或 `Map` 子节点 | 否 | 可复用或内联的目标时间到源时间偏函数;省略时为有界局部恒等映射 |
+| `gain`、`fade-in`、`fade-out` | 否 | 显式的单 Clip 混音值 |
-该包不会自动提取、规范化、duck 或分配 bus。同一 Track 内的多个 Item 与多个对等 Audio
+该包不会自动提取、规范化、duck 或分配 bus。同一 Track 内的多个 Clip 与多个对等 Audio
Track 都会作为独立输入进入 Film。输出 `{music-bed.audio}` 是普通 `AudioTrack`。
## 文字叠加层
@@ -181,77 +207,82 @@ Track 都会作为独立输入进入 Film。输出 `{music-bed.audio}` 是普通
在屏幕上显示的静态或定时文字——标题、标注、下方三分之一字幕条。
```svml
-<import as="text" from="@hypit/typography-track@1"/>
+<import as="text" from="@hypit/text-fine@1"/>
<import as="wording" from="@hypit/text@1"/>
```
-### text:Track
+### text:Flow、text:Point 与 text:Path
-文字项目的容器。
+细粒度文字没有聚合容器。每个独立标题、标签或短篇编辑文字都是一个 occurrence,并各自
+产生一条普通 VisualTrack 贡献。
```svml
<space:Canvas id="vertical" width="1080" height="1920"/>
-<space:Frame id="title-frame" within={vertical}
+<space:Frame id="title-frame" within={vertical.bounds}
left="6%" top="6%" right="94%" bottom="16%"/>
<fonts:Stack id="title-font" family="inter" weight="900" style="normal"/>
<text:Style id="title-style" recipe={recipes.text.title} font={title-font}/>
-<text:Track id="titles" timeline={speech.timeline}>
- <text:Area id="title" placement={title-frame} style={title-style} during="program">
- EDIT MEANING, NOT TIMELINES
- </text:Area>
-</text:Track>
+<text:Flow id="title" timeline={speech.timeline} within={title-frame}
+ style={title-style} z="90" align="center" during="timeline">
+ EDIT MEANING, NOT TIMELINES
+</text:Flow>
```
| 属性 | 必填 | 描述 |
|---|---|---|
| `id` | 是 | 唯一标识符 |
-| `semantic` | 是 | 来自 `time:Timeline` 的 Timeline——也用于解析基于 Selection 的项目计时 |
+| `timeline` | 是 | 拥有 occurrence 窗口的绝对 Timeline |
+| `during`、`at`/`for` 或 `start`/`end` | 三选一 | 绝对 Window、Instant 加时长,或作者声明的边界 |
+| `within`、`point` 或 `path` | 是 | 与 `Flow`、`Point` 或 `Path` 对应的位置 |
+| `style` | 是 | 由 SVS Recipe 与精确字体字节编译出的 Style |
+| `z` | 是 | 这个 occurrence 的绝对层叠顺序;它不属于 Style |
+| 形式布局 | 否 | `Flow` 的对齐/换行、`Point` 的锚定或 `Path` 的边距/方向,只写在对应 occurrence 上 |
-### text:Point、text:Area 与 text:Path
-
-每个 Item 都明确选择一种放置形式、一份精确 Style 和一种时间投影。`Area` 把流式文字放入
-`SpatialFrame`:
+每个 occurrence 都明确选择一种位置形式、一份精确 Style 和一个绝对时间表达式。`Flow`
+把流式文字放入 `SpatialFrame`:
```svml
-<text:Area id="meaning" placement={title-frame} style={title-style} during="program">
+<text:Flow id="meaning" timeline={speech.timeline} within={title-frame}
+ style={title-style} z="90" align="center" during="timeline">
MEANING
-</text:Area>
+</text:Flow>
```
| 属性 | 必填 | 描述 |
|---|---|---|
-| `id` | 是 | 稳定的 Item 身份 |
+| `id` | 是 | 稳定的文字 occurrence 身份 |
| 子内容或 `content` | 是 | 内联纯文本/富文本,或普通图 `Text` 引用;两种形式互斥 |
-| `during` | 是 | `"program"` 或 Selection 引用;也可使用 `at` 与显式 `start`/`end` |
-| `placement` | 是 | 与 Item 形式匹配的 `SpatialPoint`、`SpatialFrame` 或 `SpatialPath` |
+| 时间 | 是 | `during="timeline"`、绝对 Window,或 `at`/`for`、`until`/`for`、`start`/`end` |
+| 位置 | 是 | 与 occurrence 形式匹配的 `SpatialPoint`、`SpatialFrame` 或 `SpatialPath` |
| `style` | 是 | 由 SVS Recipe 与精确字体字节共同编译出的 `text:Style` |
+| `z` | 是 | 这个 occurrence 的绝对层叠顺序 |
+| 形式布局 | 否 | 所选 `Flow`、`Point` 或 `Path` 直接声明的布局属性 |
-`during` 属性接受字面字符串 `"program"`(表示完整 Timeline),或用于语义计时的 Selection、Segment 引用。同一套时间接口也接受作者声明的 `start`/`end` 窗口和 `at`/`for` 事件:
+`during="timeline"` 表示完整 Timeline。作者声明的 Timeline Window,或者上游语义、节拍等
+领域的投影,也可以提供普通的绝对 Window;细粒度文字组件不认识这个 Window 来自哪个领域:
```svml
<text:Style id="callout-style" recipe={recipes.text.callout} font={title-font}/>
-<text:Track id="callout" timeline={speech.timeline}>
- <text:Area id="callout-copy" placement={callout-frame}
- style={callout-style} during={story.selection.callout}>
- EXACTLY THE RIGHT MOMENT
- </text:Area>
-</text:Track>
+<text:Flow id="callout-copy" timeline={speech.timeline} within={callout-frame}
+ style={callout-style} z="90" during={program.callout}>
+ EXACTLY THE RIGHT MOMENT
+</text:Flow>
```
图中产生的文字会保留为显式边:
```svml
<wording:Value id="headline">EXACTLY THE RIGHT MOMENT</wording:Value>
-<text:Track id="callout" timeline={speech.timeline}>
- <text:Area id="callout-copy" content={headline}
- placement={callout-frame} style={callout-style} during="program"/>
-</text:Track>
+<text:Flow id="callout-copy" timeline={speech.timeline} content={headline}
+ within={callout-frame} style={callout-style} z="90" during="timeline"/>
```
通用 `Text` 只提供字符;Typography 仍然拥有文档包装、位置、时间、样式与动画。作者需要富文本
Run 时,继续使用内联 `P`/`Span`/`Break`。
-**输出:**`{titles.track}` —— 添加到 `film:Film` 的 VisualTrack。
+每个 occurrence 发布 `{callout-copy.occurrence}` 供同族文字工具使用,并发布
+`{callout-copy.visual}` 供 `film:Film` 使用。多个无关标题仍是 Film 的多个显式输入;若它们
+共享行为,应由项目组件负责协调,而不是偶然聚成一条文字集合。
## 榜单板
@@ -274,12 +305,13 @@ Run 时,继续使用内联 `P`/`Span`/`Break`。
| 属性 | 取值 |
|---|---|
-| `semantic` | 板据以计时的 Timeline |
+| `timeline` | 板据以计时的绝对 Timeline |
+| `semantic` | 仅供语义时间表达式使用的可选 Narrative 投影 |
+| `within` | 所选板型拥有独立揭示区或讲解区时使用的 `space:Frame` |
| `frame` | 一个 `space:Frame`——选中组件声明的板面位置 |
| `during` | 选中组件声明的时间形式 |
| `style` | 对应的样式记录,且只接受本变体的 |
| `terminal` | 完整板定格的 Moment。仅 `TopThree` |
-| `canvas` | 选中组件可声明的 `space:Canvas` |
| `appear-sound`、`move-sound` | 可选,Synchronized Media |
只使用所选包明确声明的时间形式;不要从另一个组件族推断 terminal 或 reveal 规则。
@@ -288,17 +320,17 @@ Run 时,继续使用内联 `P`/`Span`/`Break`。
每个变体只接受自己的那一种,至少一个,且 id 在同一块板内不可重复。
-- **`TopThreeItem`** —— `label` 与 item 自己的 `at={story.moment...}` 必填,可选 `icon` 与 `stack`,最多三条。揭示顺序由这些 Moment 的真实帧顺序决定。
+- **`TopThreeItem`** —— `label` 与 item 自己的绝对 `at={story-time...}` 必填,可选 `icon` 与 `stack`,最多三条。揭示顺序由这些 Instant 的真实帧顺序决定。
- **`ColumnItem`** —— `label` 与 `rank` 必填,可选 `icon` 与 `stack`。非 preset item 用自己的 `during` Selection;`preset="true"` 的 item 开场已在位且不写 `during`。
```svml
<ranking:ColumnStyle id="board-style" recipe={recipes.ranking.board} font={ui-font}/>
-<ranking:Column id="board" timeline={speech.timeline} canvas={vertical} frame={board-frame}
- during={story.selection.board} style={board-style}>
+<ranking:Column id="board" timeline={speech.timeline} within={vertical.bounds} frame={board-frame}
+ during={story-time.board} style={board-style}>
<ranking:ColumnItem id="row-regen" rank="1" label="ReGen" icon={icon-regen}
- during={story.selection.regen-reveal}/>
+ during={story-time.regen-reveal}/>
<ranking:ColumnItem id="row-chatgpt" rank="2" label="ChatGPT" icon={icon-chatgpt}
- during={story.selection.chatgpt-reveal}/>
+ during={story-time.chatgpt-reveal}/>
<ranking:ColumnItem id="row-remini" rank="3" preset="true" label="Remini" icon={icon-remini}/>
</ranking:Column>
```
@@ -307,15 +339,16 @@ Run 时,继续使用内联 `P`/`Span`/`Break`。
## 卡片堆
-卡片堆按深度排布卡片:一张在最前,其余向后退去,每张新卡在一个 Moment 上发出。Media Item 是把一个镜头放进一个 Frame,而卡片堆是在同一个 Frame 里维持一叠并整体移动它们。
+卡片堆按深度排布卡片:一张在最前,其余向后退去,每张新卡在一个 Moment 上发出。Visual Clip 是把一个镜头放进一个 Frame,而卡片堆是在同一个 Frame 里维持一叠并整体移动它们。
```svml
-<import as="deck" from="@hypit/deck-track@1"/>
+<import as="deck" from="@hypit/depth-stack@1"/>
```
### deck:DepthStack
-`id`、`timeline`、`canvas`、`frame` 与 `appearance` 全部必填。同一份 Timeline 提供作者时间和已放置的语义锚点。`until` 同样必填,指定这叠卡片何时结束:Moment、Selection 或 Segment 的边界,或 `8s`、`program.end` 等作者时间。Selection 或 Segment 可以用 `until-boundary="start" | "end"` 选择首尾,默认是 `end`。
+`id`、`timeline`、`within`、`frame`、`appearance` 与 `until` 全部必填。`until` 接受绝对
+Instant,例如上游从语义投影出的事件,或 `8s` 这样的作者时间。
### deck:Card
@@ -325,7 +358,7 @@ DepthStack 的直接子元素,自闭合,至少一张,按书写顺序发出
|---|---|
| `source` | 必填——静态图片、Synchronized Medium 或 Compositable Surface |
| `extent` | 静态图片必填,其余情况给了会被拒绝 |
-| `at` | 必填——这张卡发出的事件,可以是 Moment 或 `2s`、`12f` 等作者时间 |
+| `at` | 必填——绝对发牌 Instant,或 `2s`、`12f` 等作者时间 |
| `appearance` | 可选——它自己的 Recipe,否则沿用整叠的 |
| `label` | 可选——一条 `deck:Label` 记录 |
@@ -334,15 +367,15 @@ DepthStack 的直接子元素,自闭合,至少一张,按书写顺序发出
`id` 与 `font` 必填。文案来自 `content=` 引用或元素自身的文字,两个都给会被拒绝。`size`、`color`、`align`、`block`、`padding` 可选。
```svml
-<space:Frame id="deck-frame" within={vertical} left="44%" top="60%" right="98%" bottom="88%"/>
-<deck:DepthStack id="deck" timeline={speech.timeline} canvas={vertical}
- frame={deck-frame} appearance={recipes.deck.stack} until={story.moment.done}>
- <deck:Card id="card-spatial" source={icon-spatial} extent={square} at={story.moment.deal-one}/>
- <deck:Card id="card-type" source={icon-type} extent={square} at={story.moment.deal-two}/>
+<space:Frame id="deck-frame" within={vertical.bounds} left="44%" top="60%" right="98%" bottom="88%"/>
+<deck:DepthStack id="deck" timeline={speech.timeline} within={vertical.bounds}
+ frame={deck-frame} appearance={recipes.deck.stack} until={story-time.done}>
+ <deck:Card id="card-spatial" source={icon-spatial} extent={square} at={story-time.deal-one}/>
+ <deck:Card id="card-type" source={icon-type} extent={square} at={story-time.deal-two}/>
</deck:DepthStack>
```
-**输出:** `{deck.track}`——一条 VisualTrack,与 Film 中其它每一条 Track 平级。
+**输出:** `{deck.visual}`——一条 VisualTrack,与 Film 中其它每一条 Track 平级。
## 屏幕叠加层
@@ -356,10 +389,10 @@ DepthStack 的直接子元素,自闭合,至少一张,按书写顺序发出
| 时间窗 | 写法 |
|---|---|
-| 整个节目 | `during="program"` |
-| 一个 Selection | 在带有 `timeline={speech.timeline}` 的 Track 内写 `during={story.selection.x}` |
-| 一个 Moment,持续一段时长 | 在带有 `timeline={speech.timeline}` 的 Track 内写 `at={story.moment.x} for="12f"` |
-| 显式区间 | `start="…" end="…"`,可另外指定 `selection=` 或 `moment=` |
+| 整个节目 | `during="timeline"` |
+| 已解析的 Window | `during={story-time.overlay}` |
+| 绝对起点与时长 | `from="2s" for="12f"` |
+| 显式区间 | `from={story-time.start} until={story-time.end}` |
时长写作 `12f`、`250ms` 或 `1.5s`。一个 Selection
只表示一个连续区间,一个 Moment 只表示一个点;同一效果需要再次出现时,应再写一个 item。
@@ -367,13 +400,13 @@ DepthStack 的直接子元素,自闭合,至少一张,按书写顺序发出
可用的效果有十一种——`Flash`、`ColorWash`、`Vignette`、`ScanLines`、`DirectionalMatte`、`WhipVeil`、`GlitchVeil`、`Grain`、`LightLeak`、`Bokeh` 与 `TVStatic`——每种各有自己的必填属性,例如 `Flash` 的 `color` / `intensity` / `attack` / `hold` / `decay`,或 `Vignette` 的 `center-x` / `center-y` / `radius-x` / `radius-y` / `softness` / `color` / `opacity`。它们都没有默认值:一个效果要么把自己的形状说全,要么被拒绝。
```svml
-<screen:Track id="effects" timeline={speech.timeline} canvas={vertical}>
- <screen:Flash during={story.selection.overlay} z="80"
+<screen:Track id="effects" timeline={speech.timeline} within={vertical.bounds}>
+ <screen:Flash during={story-time.overlay} z="80"
color="#ffffff" intensity="0.6" attack="2" hold="2" decay="6"/>
</screen:Track>
```
-**输出:** `{effects.track}`——一条 VisualTrack。
+**输出:** `{effects.visual}`——一条 VisualTrack。
## 评论贴纸
@@ -385,21 +418,21 @@ DepthStack 的直接子元素,自闭合,至少一张,按书写顺序发出
`comment:Style` 必须为空,接受 `id`、`recipe` 与 `font`,全部必填。Recipe 承载整张卡的外观——背景、描边、圆角、气泡尾、头像、三行文字,以及进入/停留/退出的动效——每个键都有默认值,所以一份 recipe 只需写它要改的部分。
-`comment:Track` 接受 `id`、`canvas` 与 `semantic`,三者皆为必填。
+`comment:Track` 接受 `id` 与 `timeline`,两者皆为必填。
`comment:Sticker` 必填 `id`、`frame` 与 `style`,时间窗与上面的屏幕叠加层相同。它的文案来自 `comment=` 属性或元素自身的文字,两个都给会被拒绝。可选的 `author`、`header` 与 `meta` 各接受字符串或 Text 引用,`avatar` 接受一张图片;这里没有 `z`,层叠顺序来自 recipe 的 `stack-order`。
```svml
<comment:Style id="social" recipe={recipes.comment} font={ui-font}/>
-<comment:Track id="comments" canvas={vertical} timeline={speech.timeline}>
+<comment:Track id="comments" timeline={speech.timeline}>
<comment:Sticker id="one" frame={comment-frame} style={social} avatar={viewer-avatar}
- author="@viewer" meta="Featured" during={story.selection.reaction}>
+ author="@viewer" meta="Featured" during={story-time.reaction}>
原来它把字幕钉在词上,而不是钉在秒上。
</comment:Sticker>
</comment:Track>
```
-**输出:** `{comments.track}`——一条 VisualTrack。
+**输出:** `{comments.visual}`——一条 VisualTrack。
## 组合示例
@@ -411,69 +444,70 @@ DepthStack 的直接子元素,自闭合,至少一张,按书写顺序发出
<import as="fonts" from="@hypit/fonts-open@1"/>
<import as="media" from="@hypit/media@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
-<import as="media-track" from="@hypit/media-track@1"/>
-<import as="text" from="@hypit/typography-track@1"/>
+<import as="visual" from="@hypit/visual-track@1"/>
+<import as="text" from="@hypit/text-fine@1"/>
<import as="audio" from="@hypit/audio-track@1"/>
<import as="space" from="@hypit/spatial@1"/>
+<import as="time" from="@hypit/timeline-author@1"/>
+
+<time:Clock id="clock" frame-rate="30"/>
<!-- Captions: primary style for all text -->
<fonts:Stack id="caption-font" family="inter" weight="700" style="normal"/>
<fonts:Stack id="title-font" family="inter" weight="900" style="normal"/>
<caption-fine:Style id="base-caption" recipe={recipes.caption.base} font={caption-font}/>
-<caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline}>
+<caption-fine:Caption id="captions" document={story.caption} timing={story-captions}
+ timeline={speech.timeline} within={vertical.bounds}>
<caption-fine:Use style={base-caption}/>
- </caption-fine:Track>
+ </caption-fine:Caption>
<!-- 共享位置是显式边,与 Media/Text 外观分开。 -->
<space:Canvas id="vertical" width="1080" height="1920"/>
-<space:Frame id="title-frame" within={vertical}
+
+<space:Frame id="title-frame" within={vertical.bounds}
left="6%" top="6%" right="94%" bottom="16%"/>
-<space:Frame id="card-frame" within={vertical}
+
+<space:Frame id="card-frame" within={vertical.bounds}
left="10%" top="20%" right="90%" bottom="70%"/>
-<!-- Media:Selection 期间显示一个普通 Item -->
+<!-- Media:Selection 期间显示一个普通 Clip -->
<pipeline:Normalize id="card-media" source={motion.video}
- video="primary-moving" audio="none" span-authority="video" frame-rate="30"/>
-<media-track:Track id="cards" timeline={speech.timeline} canvas={vertical}>
- <media-track:Item media={card-media.media} frame={card-frame}
- during={story.selection.demo} appearance={recipes.media.card} motion={recipes.motion.card}/>
-</media-track:Track>
+ video="primary-moving" audio="none" span-authority="video" clock={clock}/>
+<visual:Track id="cards" timeline={speech.timeline}>
+ <visual:Clip media={card-media.media} frame={card-frame}
+ during={story-time.demo} z="40" fit="cover" treatment={recipes.visual.card}/>
+</visual:Track>
<!-- Text: persistent title overlay -->
<text:Style id="title-style" recipe={recipes.text.title} font={title-font}/>
-<text:Track id="titles" timeline={speech.timeline}>
- <text:Area id="meaning" placement={title-frame} style={title-style} during="program">
- MEANING
- </text:Area>
-</text:Track>
+<text:Flow id="meaning" timeline={speech.timeline} within={title-frame}
+ style={title-style} z="90" align="center" during="timeline">
+ MEANING
+</text:Flow>
<!-- Audio:先规范化一份已声明素材,再把它放满整个节目 -->
<media:Audio id="music" src="./assets/music.wav"/>
<pipeline:Normalize id="music-media" source={music}
- video="none" audio="default" span-authority="audio" frame-rate="30"/>
+ video="none" audio="default" span-authority="audio" clock={clock}/>
<audio:Track id="music-bed" timeline={speech.timeline}>
- <audio:Item source={music-media.media} during="program"
- playback="loop-end" gain="0.28" fade-in="600ms" fade-out="800ms"/>
+ <audio:Clip source={music-media.media} during="timeline"
+ 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"/>
+ </audio:Clip>
</audio:Track>
<!-- 所有对等 Track 都进入 Film -->
-<import as="sound" from="@hypit/sound@1"/>
-<sound:Style id="voice-style"/>
-<sound:Track id="voice" timeline={speech.timeline}>
- <sound:Use style={voice-style}/>
-</sound:Track>
-
-<film:Film id="main" canvas={vertical} timeline={speech.timeline} appearance={recipes.film.vertical}>
- <film:Track source={performance.visual}/>
- <film:Track source={voice.audio}/>
+<film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline} appearance={recipes.film.vertical}>
+ <film:Track source={picture.visual}/>
+ <film:Track source={mix.audio}/>
<film:Track source={cards.visual}/>
- <film:Track source={captions.track}/>
- <film:Track source={titles.track}/>
+ <film:Track source={captions.visual}/>
+ <film:Track source={meaning.visual}/>
<film:Track source={music-bed.audio}/>
</film:Film>
```
-本例的 Recipe 将表演画面放在 10,Media 放在 40,字幕放在 70,文字放在 90。
+本例的 Recipe 将已放置的画面放在 10,Visual Clip 放在 40,字幕放在 70,文字放在 90。
数值越高,绘制位置越靠前;作者按作品需要选择这些关系。
diff --git a/services/whisperx/README.md b/services/whisperx/README.md
index 7aa2cdc8..d337b3cc 100644
--- a/services/whisperx/README.md
+++ b/services/whisperx/README.md
@@ -13,7 +13,7 @@ canonical 16 kHz mono PCM s16 WAV
```
It does not run FFmpeg, modify the authored script, split caption cues, infer SVML Segments, cache
-Build results or create a SemanticTake. Missing WhisperX word timing stays missing; the author-side
+Build results or create a media-semantic bundle. Missing WhisperX word timing stays missing; the author-side
semantic projection combines this evidence with one explicit Script Segment later.
## Install
diff --git a/skills/hypit/SKILL.md b/skills/hypit/SKILL.md
index ef992149..1e1ab19f 100644
--- a/skills/hypit/SKILL.md
+++ b/skills/hypit/SKILL.md
@@ -48,10 +48,12 @@ what draws attention, and what each change accomplishes. Give those relationship
components can complete their local layout and motion. Hypit supplies shared authoring and execution
interfaces for both existing and project-defined components.
-The work has one Timeline and a canvas. Placed Takes add semantic anchors where they belong;
-components give the picture useful structure. Time can contain speech, gaps, overlaps or wholly
-authored animation. Space can contain independent contributions or a coordinated scene with its own
-internal tree. [System relationships](references/production/system.md) explains this adaptive
+The work has one finite Timeline and one Canvas. Prepared media has local domains and Extents;
+domain projectors can translate local evidence through equal-length absolute Windows without becoming
+Timeline contents. Semantic alignment, musical beats and authored events are peer sources of absolute
+time. Visual and Audio Clips consume ordinary media occurrences with explicit Windows. Time can contain speech, gaps, overlaps or
+wholly authored animation. Space can contain independent contributions or a coordinated scene with
+its own internal tree. [System relationships](references/production/system.md) explains this adaptive
organization and connects it to materials and execution.
Choose component boundaries through shared behavior: coordinated layout and motion can share a
@@ -72,14 +74,14 @@ presentation with its meaning. Preserve what each event responds to. In an autho
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.
-A-roll names the performance carrying a passage. Its placed material and semantic timing remain
-available while the picture changes size, position, visibility or visual company. Present the current
-Timeline footage through Performance or a project scene; supply independent media explicitly when
-the work needs a different playback relationship. Choose what leads the picture from the current
-idea. A direct cut or a continuous movement can each express that change. Spatial grouping and timing
-are independent choices, so a whole scene can respond to a Moment and separate components can share
-that Moment. [Voice and performance](references/playbooks/craft/voice-and-performance.md) explains
-the role; [Performance](references/production/performance.md) explains its visual use.
+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
+media as any other material. Place its picture through a Visual Clip or project scene, and its sound
+through an Audio Clip, each with an explicit absolute Window and sampling choice. Choose what leads the picture
+from the current idea. A direct cut or continuous movement can each express that change. Spatial
+grouping and timing are independent choices, so a whole scene can respond to a Moment and separate
+components can share that Moment. [Voice and performance](references/playbooks/craft/voice-and-performance.md)
+explains the role; [Visual Clips](references/production/visual-clips.md) explains its use.
## Direct the material
@@ -285,14 +287,14 @@ practical, revisit that choice and carry the improvement into the work and its n
| directing visual effects or MG in motion: states, actions, handoffs, persistent objects and visual rhythm | `references/playbooks/craft/motion-graphics.md` |
| deciding which generated images or videos should depend on which references, including people, places, views and continuing props | `references/playbooks/craft/generated-dependencies.md` |
| mixing performed or B-roll source sound with chosen music and effects, including balance, ducking and continuity | `references/playbooks/craft/sound-mix.md` |
-| presenting existing Timeline sound, local gain, silence, fades or explicit source blending | `references/production/sound.md` |
+| presenting existing Timeline sound, local gain, silence, fades or explicit source blending | `references/production/audio-clips.md` |
| writing Sources, Recipes, and Runs, reusing produced work, adding a component | `references/production/authoring.md` |
| imports, output references, literal values or Recipe rules | `references/production/source-syntax.md` |
| choosing an existing Prompt Kit, assembling its wording or authoring a new one | `references/production/prompt-kits.md` |
| Run syntax, material Targets, Candidates, Run Fragments or reusing produced media | `references/production/runs.md` |
-| admitting or reusing images/video/audio for the role this work gives them, model references, normalization, SemanticTakes, trims or processed variants | `references/production/media.md` |
-| presenting independent images, prepared video or surfaces, playback and replacement sequences | `references/production/media-presentation.md` |
-| placing independent music, narration, ambience or effects and selecting source playback | `references/production/audio-presentation.md` |
+| admitting or reusing images/video/audio, model references, normalization, local domains, NarrativeAlignment, trims or processed variants | `references/production/media.md` |
+| placing independent images, prepared video or surfaces and choosing source playback | `references/production/visual-clips.md` |
+| placing independent music, narration, ambience or effects and selecting source playback | `references/production/audio-clips.md` |
| downloading a reference or source video from a link with yt-dlp | `references/production/video-downloads.md` |
| capturing a website, recording a page interaction or exporting a local HTML graphic | `references/production/browser-capture.md` |
| composing, correcting, resizing, cropping or cutting out an image | `references/production/image-operations.md` |
@@ -301,9 +303,9 @@ practical, revisit that choice and carry the improvement into the work and its n
| choosing or finding fonts, using local font files, multilingual text, Emoji or Typography | `references/production/fonts-and-text.md` |
| which installed Surface to use, or whether to write a project component | `references/production/vocabulary.md` |
| sharing a component, Prompt Kit, Model, or Provider across projects | `references/production/component-sharing.md` |
-| placing Takes, gaps, overlap, complete duration or a pure MG work on one Timeline | `references/production/timeline.md` |
+| constructing Timeline end, Instants, Windows, Extents, Placements, gaps, overlap or a pure MG work | `references/production/timeline.md` |
| choosing content ownership and composing visual/audio contributions | `references/production/tracks.md` |
-| presenting existing Timeline footage with broad or local Uses, a moving viewport or a custom Performance Style | `references/production/performance.md` |
+| placing footage or independent pictures through Visual Clips, or deciding when coordinated behavior needs a component | `references/production/visual-clips.md` |
| writing a project Track with new layout, semantic events or persistent state | `references/production/track-authoring.md` |
| drawing a component's elements, animation, resources or prepared surfaces | `references/production/component-visuals.md` |
| writing a Caption family with new word relationships, scheduling or layout | `references/production/caption-authoring.md` |
diff --git a/skills/hypit/references/creation/project-files.md b/skills/hypit/references/creation/project-files.md
index 6bc8e3c2..1c6920d4 100644
--- a/skills/hypit/references/creation/project-files.md
+++ b/skills/hypit/references/creation/project-files.md
@@ -209,8 +209,9 @@ Runtime's execution state.
`hypit get` is useful when handing over a particular output. Exported image/video/audio files can be
selected as file Candidates. A Composite export contains `value.json` and its resource files for
inspection and transport; that document uses the Result value format, whereas a Run `<value>` accepts
-a StoredValue wrapper. To retain a SemanticTake's structured reuse, keep its Result available and use
-`build-record`. [Builds and Results](../production/builds.md) explains repository selection and export.
+a StoredValue wrapper. To retain structured normalized media, local-domain or alignment reuse, keep
+its Result available and select each required Output with `build-record`. [Builds and Results](../production/builds.md)
+explains repository selection and export.
## Resume from present facts
diff --git a/skills/hypit/references/creation/script-and-time.md b/skills/hypit/references/creation/script-and-time.md
index 8c8f9d99..06676e53 100644
--- a/skills/hypit/references/creation/script-and-time.md
+++ b/skills/hypit/references/creation/script-and-time.md
@@ -7,10 +7,10 @@ that picture and sound should follow. It also covers measured delivery and wordl
[Source syntax](../production/source-syntax.md) covers the surrounding imports, references, Recipes
and Runs; [Tracks](../production/tracks.md) covers the consumers of Script meaning.
-[Timeline authoring](../production/timeline.md) places Takes, allows gaps and overlaps, and declares
+[Timeline authoring](../production/timeline.md) places local temporal domains, allows gaps and overlaps, and declares
the complete work, including pure MG with no Script.
[Media preparation](../production/media.md) explains connecting actual footage to a Segment, and
-[Runs](../production/runs.md) explains targeting material and reusing produced Takes.
+[Runs](../production/runs.md) explains targeting material and reusing produced media, domains and alignment evidence.
## Script is the target's sole verbal authority
@@ -21,8 +21,8 @@ the purpose of a passage, but the adopted wording appears in Source only once.
Choose Script structure from the thought being expressed and the performance carrying it:
-- a **Segment** groups a performable passage around its thought, delivery and action; its accepted
- media can become one SemanticTake;
+- a **Segment** groups a performable passage around its thought, delivery and action; accepted media
+ can be aligned to it without becoming a compound semantic-media object;
- a **Role Cue** assigns a spoken turn to a performer and carries that label into the model's dialogue;
- **Dual Text** gives one authored unit separate display and pronunciation text;
- `||` says that one on-screen **Caption Cue** hands off to the next after a complete Alignment Unit;
@@ -136,8 +136,9 @@ 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 and start/end anchors. Its
-associated normalized media determines the duration, and its SemanticTake has an empty word array.
+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.
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
@@ -164,15 +165,15 @@ A chat animation, diagram or kinetic-text piece can instead be drawn entirely by
messages and changes still carry meaning; the author chooses when the audience receives them and
how long they need to read. Keep content and event timing together in the owning component's Source.
An event can have an identity such as `question` or `reveal` and an authored `at="2.6s"` without
-inventing spoken words or a media-backed Segment. Film time is declared through a Timeline with an explicit end and zero Takes;
+inventing spoken words or a media-backed Segment. Film time is declared through a Timeline with an explicit end;
[composition and rendering](../production/rendering.md#compose-an-authored-animation) shows the form.
Choose timing per relationship, not once for the whole video. A spoken Moment can introduce a chat
scene whose messages then unfold at authored intervals. Conversely, an authored animation can reveal
-one item on a spoken Moment. A projected expression such as `instant="moment.cue + 12f"` with
-`moment={story.moment.intro}` keeps an interval relative to that spoken event. The event's trigger
-and its entrance duration are different choices:
-`at={story.moment.answer}` locates the answer; ten frames can give its arrival a particular character.
+one item on a spoken Moment. Ask the Narrative projection to publish that Moment as an absolute
+Instant, optionally with an explicit offset, then pass the result to the component. The event's
+trigger and its entrance duration are different choices: `at={story-time.answer}` locates the
+answer; ten frames can give its arrival a particular character.
## Measure before choosing durations
@@ -217,8 +218,8 @@ energy while finding a performable shape, then measure the affected wording agai
applies this judgment to the selected model's request range.
Measurement balances the intended speaking density and sizes generation; it supplies no timeline
-anchors. Once a Take is accepted, normalize it, align its actual speech to its Script Segment, and
-assemble the resulting SemanticTakes into the Timeline. The literal duration answers how much
+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.
diff --git a/skills/hypit/references/playbooks/craft/b-roll.md b/skills/hypit/references/playbooks/craft/b-roll.md
index 06501f7f..831e44ef 100644
--- a/skills/hypit/references/playbooks/craft/b-roll.md
+++ b/skills/hypit/references/playbooks/craft/b-roll.md
@@ -30,7 +30,7 @@ display can use part of a longer source; the generation request's duration does
display duration.
**A visual thought across several pictures** can convey a habit, history, process or attitude.
-The pictures may be separate Items or scenes inside one generated clip. Their changes can follow
+The pictures may be separate Clips or scenes inside one generated clip. Their changes can follow
the argument's beats without assigning a cut to every spoken noun. When the reference's exact
picture-to-claim correspondence matters, preserve that closer relationship instead.
@@ -43,13 +43,13 @@ independently arranged media may serve the same visual purpose without that Kit.
A still can fill the Canvas; a video can play beside a moving presenter; either can sit within a
frame, crop, mask or designed border. The chosen picture can lead attention while the performance
-remains visible elsewhere, or it can occupy the whole view while that performance's Sound
+remains visible elsewhere, or it can occupy the whole view while that performance's audio
continues. Its location and paint order follow the composition, not its B-roll name.
-For an independent picture, [Media presentation](../../production/media-presentation.md) supplies
+For an independent picture, [Visual Clip authoring](../../production/visual-clips.md) supplies
the image or prepared video, its Frame, appearance and playback. A still has a display Window
-without needing video conversion. [Performance](../../production/performance.md) presents footage
-already placed on the Timeline and retains its source position as its view changes. When material,
+without needing video conversion. A project component can retain a time-bearing source's position
+while its view changes. When material,
presenter and graphics share layout or motion, a [project component](../../production/component-design.md)
can own that visual behavior together. A border or animated frame is a presentation choice; it
does not require a new kind of source material. [Spatial layout](../../production/spatial.md) owns
@@ -64,14 +64,14 @@ owns how those audible contributions meet.
A picture answering a spoken claim can follow a Selection or Moment; a musical beat or physical
action may call for authored time. Its visual Window need not start or end with a speaker's
appearance. A partner may begin speaking while the last lifestyle picture stays up, then become
-visible later: the sound-picture handoff forms a J-cut. The placed Takes and Sound establish whose
+visible later: the sound-picture handoff forms a J-cut. An Audio Clip establishes whose
words are heard while the visual composition chooses when views change.
Choose the end by the thought, action and time needed to read the picture. A still remains present
through its Window; a moving source also has its own playback span. Let a clip finish when its
last action matters, or cut it where the work gains the better beat. Holding, looping or retiming
is another expressive choice, not a consequence of the Window being longer than the source.
-[Media presentation](../../production/media-presentation.md#keep-display-time-and-source-playback-distinct)
+[Visual Clip authoring](../../production/visual-clips.md#keep-destination-time-and-source-sampling-distinct)
owns those sampling modes.
Adjacent pictures may meet at one semantic boundary, bridge the pause between words or intentionally
@@ -88,7 +88,7 @@ view earns its change when it reveals what the wider view could not; a quiet con
motion may deserve time to finish. [Sound and mix](sound-mix.md) owns how recorded, generated or
separately authored sound supports that material.
-The same [Timeline](../../production/timeline.md) holds performed Takes, gaps and directly authored
-intervals. Independent material can occupy any of them. A wordless performed passage can supply
+The same [Timeline](../../production/timeline.md) resolves placed local domains, gaps and directly authored
+intervals without holding media. Independent material can occupy any of them. A wordless performed passage can supply
its own reusable media boundaries; a passage made entirely of pictures and graphics can use
authored time. Neither requires a hidden speaking picture.
diff --git a/skills/hypit/references/playbooks/craft/caption-tracking.md b/skills/hypit/references/playbooks/craft/caption-tracking.md
index e0f783d0..b96b142f 100644
--- a/skills/hypit/references/playbooks/craft/caption-tracking.md
+++ b/skills/hypit/references/playbooks/craft/caption-tracking.md
@@ -37,7 +37,7 @@ for this placement task. Use the installed tool or the provider's
[face-detection example](https://docs.cloud.google.com/video-intelligence/docs/samples/video-detect-faces)
for actual invocation and existing authorization for any paid request. Another suitable detector or
manual measurement can supply the same authored data. The stable Hypit input is the resulting
-RegionTimeline, so detector invocation can remain an external, project-side preparation step.
+Region Track, so detector invocation can remain an external, project-side preparation step.
GVI's timestamped boxes are observations, not Script Roles or ready-to-use Hypit head tracks. Its
[response schema](https://docs.cloud.google.com/video-intelligence/docs/reference/rest/v1/AnnotateVideoResponse#TimestampedObject)
@@ -93,8 +93,7 @@ For example, this is a three-frame data-shape illustration, not a ready timeline
```svs
heads.default {
- frame-count: 3;
- tracks: [
+ series: [
{"id":"GUEST","regions":[[0.12,0.09,0.20,0.26],null,[0.13,0.10,0.20,0.26]]}
];
}
@@ -103,18 +102,20 @@ heads.default {
## Connect the placement to Caption
```svml
-<space:RegionTimeline id="heads" within={vertical} recipe={tracking.heads.default}/>
-<caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline} regions={heads}>
+<import as="region" from="@hypit/region-track@1"/>
+<region:Track id="heads" within={vertical.bounds} timeline={speech.timeline}
+ recipe={tracking.heads.default}/>
+<caption-fine:Caption id="captions" document={story.caption} timing={story-captions}
+ timeline={speech.timeline} within={vertical.bounds} regions={heads}>
<caption-fine:Use style={caption-style}/>
-</caption-fine:Track>
+</caption-fine:Caption>
```
-The RegionTimeline's ids match Script Roles. Fine places a single-Role Cue at that region's top
+The Region Track series ids match Script Roles. Fine places a single-Role Cue at that region's top
center; `anchor-x: center` and `anchor-y: bottom` put the Cue above it. The Style still owns its width,
font and motion. Supplying `regions` requires every Cue on that Track to have one Script Role, even
when that particular Role uses fixed placement. Author the relevant Role Cues in Script. The
-`@hypit/spatial` and `@hypit/caption-fine` READMEs own the exact data behavior.
+`@hypit/region-track` and `@hypit/caption-fine` READMEs own the exact data behavior.
## Inspect the actual placement
diff --git a/skills/hypit/references/playbooks/craft/captions.md b/skills/hypit/references/playbooks/craft/captions.md
index d1f16481..ed4402b9 100644
--- a/skills/hypit/references/playbooks/craft/captions.md
+++ b/skills/hypit/references/playbooks/craft/captions.md
@@ -43,7 +43,7 @@ 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. Caption joins that truth to the actual Timeline;
+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.
@@ -200,7 +200,7 @@ project `.svs`; a set that has earned reuse across works can become an ordinary
under its owner's scope. Such a collection preserves the family, Recipe and intended use together
rather than turning isolated parameter values into universal defaults.
-Caption Track Uses choose when those Styles apply, optionally filtered by speaker. Cue content
+Caption Uses choose when those Styles apply, optionally filtered by speaker. Cue content
stays complete when presentation changes midway through a phrase. [Caption styling and coverage](../../production/caption-presentation.md) explains
overrides, Segment-wide selections, word attributes and hiding selected captions with a Hidden Style.
@@ -212,11 +212,11 @@ explicit Style Recipes. Role overrides can distinguish podcast hosts; a tracked
moving placement point without changing the verbal pipeline.
```svml
-<caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline}>
+<caption-fine:Caption id="captions" document={story.caption} timing={story-captions}
+ timeline={speech.timeline} within={vertical.bounds}>
<caption-fine:Use style={primary-caption}/>
<caption-fine:Use role="GUEST" style={guest-caption}/>
- </caption-fine:Track>
+ </caption-fine:Caption>
```
This excerpt assumes the imported Surfaces, fonts and Styles already declared in the Source.
diff --git a/skills/hypit/references/playbooks/craft/motion-graphics.md b/skills/hypit/references/playbooks/craft/motion-graphics.md
index 56855f26..529e54a0 100644
--- a/skills/hypit/references/playbooks/craft/motion-graphics.md
+++ b/skills/hypit/references/playbooks/craft/motion-graphics.md
@@ -39,11 +39,11 @@ only the outer panels changes less than the audience may think, while removing a
the remaining layout to be recomposed. The film's Treatment owns its particular palette, ornament
and attitude.
-Work with source media as part of that language. A moving viewport changes how an existing Take is
-seen; it does not change the Take's performed time. An independently moving image, a drawn border
+Work with source media as part of that language. A moving viewport changes how time-bearing source footage is
+seen; it does not change its performed time. An independently moving image, a drawn border
and a caption may share a moment without having the same visual owner. When footage and graphics
-must move as one scene, their shared geometry can be directed together. [Performance](../../production/performance.md)
-owns the current Timeline footage, and [component design](../../production/component-design.md)
+must move as one scene, their shared geometry can be directed together. [Visual Clip](../../production/visual-clips.md)
+owns time-bearing footage, and [component design](../../production/component-design.md)
owns the implementation boundary.
## Give events and movement different jobs
diff --git a/skills/hypit/references/playbooks/craft/screen-demonstrations.md b/skills/hypit/references/playbooks/craft/screen-demonstrations.md
index 7f0cee11..3f029d37 100644
--- a/skills/hypit/references/playbooks/craft/screen-demonstrations.md
+++ b/skills/hypit/references/playbooks/craft/screen-demonstrations.md
@@ -46,6 +46,6 @@ while deciding what the presenter, Caption and other graphics contribute beside
owns the animation around or within an authored demonstration.
[Browser capture](../../production/browser-capture.md) owns saving a real page or recording,
-[Media presentation](../../production/media-presentation.md) owns its playback and crop, and
+[Media presentation](../../production/visual-clips.md) owns its playback and crop, and
[component design](../../production/component-design.md) owns an editable screen scene. Choose the
realization that serves this passage's screen role.
diff --git a/skills/hypit/references/playbooks/craft/sound-mix.md b/skills/hypit/references/playbooks/craft/sound-mix.md
index d691b2d7..0879f347 100644
--- a/skills/hypit/references/playbooks/craft/sound-mix.md
+++ b/skills/hypit/references/playbooks/craft/sound-mix.md
@@ -9,14 +9,14 @@ owns who performs the words and where that voice comes from.
In speaking-video A-roll, the person's picture, words and voice belong to the same performed Take.
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 Take's
-audio through [Sound](../../production/sound.md) according to what this passage should actually play.
+separately. A wordless performance may carry its own sound or be silent. Present the selected source's
+audio through [Audio Clip](../../production/audio-clips.md) according to what this passage should actually play.
B-roll can be a still, a silent video, or video with useful source sound. Its visual role alone does
not decide whether the audience hears that sound. A lifestyle shot might contribute a particular
door, footstep or burst of laughter; a picture covering a presenter's explanation may contribute no
-audio at all. [Media](../../production/media-presentation.md#include-sound-deliberately) makes source
-audio an explicit choice, leaving the selected performance voice available beneath a silent picture.
+audio at all. [Audio Clip](../../production/audio-clips.md) makes source audio an explicit
+choice, leaving the selected performance voice available beneath a silent picture.
Listen to what the chosen material already contributes before adding sound. Music can carry pace,
mood or a change of thought; a short effect can give contact, reveal or transition an audible edge.
@@ -51,9 +51,9 @@ follow that event within the component. Music or another independently directed
an authored span of the Film. Choose the time relationship from what makes the sound happen; the
same visual and audible event can share a cause without being forced into separate timing schemes.
-The owner follows that relationship. [Sound](../../production/sound.md) presents audio from placed
-Takes; [Audio Track](../../production/audio-presentation.md) places independent audio; Media or a
-project component can publish sound coupled to its own picture and events. Film includes the wanted
+The owner follows that relationship. [Audio Clip](../../production/audio-clips.md) presents
+time-bearing source audio; [Audio Clips](../../production/audio-clips.md) place independent audio;
+a project component can publish audio coupled to its own picture and events. Film includes the wanted
audio contributions explicitly. These are composition choices, while the installed packages own
their exact playback, trigger and gain syntax.
diff --git a/skills/hypit/references/playbooks/craft/video-direction.md b/skills/hypit/references/playbooks/craft/video-direction.md
index 2d80a5a9..e831989f 100644
--- a/skills/hypit/references/playbooks/craft/video-direction.md
+++ b/skills/hypit/references/playbooks/craft/video-direction.md
@@ -275,7 +275,8 @@ reference inputs, not from a one-image-per-shot correspondence.
A prompt-directed jump cut asks the generator for an edited rhythm; it does not inspect or trim the
returned media. When produced footage needs a deterministic cut, speed change or trim, use the
-corresponding media operation and align the edited result before it becomes a SemanticTake.
+corresponding media operation before normalization and alignment. The edited media, local domain and
+alignment remain separate facts.
## Size the request around the delivery
diff --git a/skills/hypit/references/playbooks/craft/voice-and-performance.md b/skills/hypit/references/playbooks/craft/voice-and-performance.md
index 098f01b0..ae91b79b 100644
--- a/skills/hypit/references/playbooks/craft/voice-and-performance.md
+++ b/skills/hypit/references/playbooks/craft/voice-and-performance.md
@@ -12,11 +12,12 @@ spoken words acquire local timing through semantic preparation. Visible performa
picture and sound together; audio-only performance carries the passage while other contributions
supply its picture.
-Timeline assembly places the prepared Take within the complete work, ordinarily after the previous
-Take, or at an authored position.
+Timeline construction uses the prepared media's Extent to create an absolute Window within the
+complete work, ordinarily after the previous passage, or at an authored position.
The work can also contain graphics-only passages before, between or after those performances.
-[Timeline authoring](../../production/timeline.md) owns the exact
-SemanticTake assembly and projection mechanism.
+[Timeline authoring](../../production/timeline.md) owns the exact temporal DAG;
+[semantic projection](../../production/timing.md) maps separate NarrativeAlignment evidence through
+its complete local domain and equal-length Window.
For spoken work, ask **who is speaking this Segment?** The selected visible performance carries
words, mouth movement, gesture, gaze, delivery, picture, and sound together.
@@ -30,30 +31,31 @@ and Effects are authored against the time that performance established. If an ed
performance's actual length, prepare and align the edited media before assembly.
A wordless Segment can identify a real performed passage, such as a dance or reaction. Its prepared
-media supplies start/end boundaries without spoken words. A graphics-only interval can instead
-occupy the Timeline directly, with no Take. Choose from the content the passage actually uses.
+media supplies a local domain without spoken words. A graphics-only interval can instead contribute
+an authored Span to Timeline with no media. Choose from the content the passage actually uses.
## Keep the performance role separate from the picture
A-roll identifies a performance's role in the work. Its accepted material, Script relationship and
-Timeline placement persist while the author changes its visual use. The picture can lead the frame,
+Timeline Window persist while the author changes its visual use. The picture can lead the frame,
share space, appear more than once, become part of a diagram or leave the picture entirely. A large
app recording can lead attention while a small presenter supplies the passage's words and timing.
-Several such changes can happen within one Take; a visual treatment can also continue across Takes.
+Several such changes can happen within one source Window; a visual treatment can also continue
+across several sources.
The covering B-roll may even show the same person doing a silent lifestyle action. Seeing a person
-while hearing words does not by itself make that picture the speaking Take or create a new speech
-source. Sound presents the placed performance's audio, while the visual contribution chooses what
-to show. The same source clip can also serve as an independently timed replay or example elsewhere.
+while hearing words does not by itself make that picture the speaking source or create a new speech
+source. An Audio Clip plays the explicitly declared performance audio, while a Visual Clip
+chooses what to show. The same source clip can also serve as an independently timed replay or example elsewhere.
Its role follows that use; size, crop, transparency and the presence of a face do not establish it.
-Follow the relationship the picture needs: [Performance](../../production/performance.md) and project
-scenes can present the current Timeline footage; [Media](../../production/media-presentation.md)
-receives independently supplied material and playback choices. A change of emphasis can be a direct
+Follow the relationship the picture needs: a [Visual Clip](../../production/visual-clips.md) places
+one source occurrence, while a project scene can coordinate several materials and events. A change
+of emphasis can be a direct
cut, a held arrangement or a continuous motion. Decide from the idea and viewing rhythm. For a
continuous move, retain the source playback position while directing the viewport's motion; for a
direct cut, make the two intended states meet at the chosen event. Speech remains independently
-connected through [Sound](../../production/sound.md).
+connected through an [Audio Clip](../../production/audio-clips.md).
The [presenter-led explainer guide](../formats/presenter-led-explainer.md) develops the whole-work
relationship among performance, demonstration and graphics. [Graphic composition](graphic-compositions.md) owns
@@ -73,16 +75,16 @@ the listening rhythm. For ordinary creator speech, podcast turns, interviews and
makes a direct join between the prepared Segment Takes 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 the Timeline's explicit
-Take positions. [Timeline authoring](../../production/timeline.md) supports gaps and overlaps directly.
+Deliberate interruption, overlapping dialogue or musical phrasing can use explicit Window positions.
+[Timeline authoring](../../production/timeline.md) supports gaps and overlaps directly.
The sources retain their local timing; a crossfade or other coordinated picture treatment belongs
-to the visual component owning that behavior. Sequential placement remains the concise ordinary
+to the visual component owning that behavior. Sequential Window construction remains the concise ordinary
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 Performance. A supplied recording
+actual sound to Script; 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,
@@ -147,8 +149,9 @@ 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-only SemanticTake carries the A-roll role even though it contributes no picture;
-Media Track, Typography, MG, or another visual Track supplies what the viewer sees.
+The resulting audio is normalized and aligned like any other performed media. 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.
Choose audio-only A-roll because the passage itself is independently narrated, not merely because
B-roll or graphics happen to hide a visible performance. Use Voice Design to establish the person's
diff --git a/skills/hypit/references/playbooks/formats/presenter-led-explainer.md b/skills/hypit/references/playbooks/formats/presenter-led-explainer.md
index 313996a7..5252dfcd 100644
--- a/skills/hypit/references/playbooks/formats/presenter-led-explainer.md
+++ b/skills/hypit/references/playbooks/formats/presenter-led-explainer.md
@@ -27,17 +27,19 @@ number or comparison helps the viewer read that demonstration.
## Compose the performance and its presentation independently
-A Take supplies accepted performance, media and local word timing. Place it on the complete Timeline;
-the picture's arrangement can change several times during that same Take. 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 Takes. Spoken segment boundaries do not prescribe scene
-boundaries or camera cuts.
-
-Use [Performance](../../production/performance.md) for presentation of the Timeline's existing visual
-material and [Media](../../production/media-presentation.md) for independently supplied material.
+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
+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
+scene boundaries or camera cuts.
+
+Use [Visual Clips](../../production/visual-clips.md) for both time-bearing footage and independently
+supplied material.
Treat the accepted footage as available material for the changing picture: it can fill a view,
appear in several views, join a comparison or disappear while the argument continues. A project
-scene can consume its Timeline mapping alongside other inputs when their layout or action belongs
+scene can consume its ordinary media and Window alongside other inputs when their layout or action belongs
together. Let visual emphasis follow who or what currently carries the idea, including returning
to the presenter for a reaction or direct address.
@@ -49,7 +51,7 @@ rhythm. Full-frame, inset and cutout describe appearances, not separate producti
Speech sound remains an independently connected contribution when MG covers the presenter. Genuinely
independent narration uses the [narration-led relationship](narration-led-demo.md). A montage or silent
-ending can occupy ordinary time outside any Take: the complete Timeline has room for both semantic
+ending can occupy ordinary authored time: the complete Timeline has room for both semantic
anchors and independently authored events. No invented performance is needed to create that room.
## Direct material for its intended uses
@@ -150,7 +152,7 @@ full picture uses the supplied media/Result archive. The default Run reuses that
| --- | --- |
| How did the design change, and what made the revisions useful? | [Treatment and craft notes](https://github.com/hypit-ai/hypit/blob/main/examples/complex-explainer/productions/explainer/CRAFT-NOTES.md) |
| How does a spoken phrase become a scene event? | [Script](https://github.com/hypit-ai/hypit/blob/main/examples/complex-explainer/productions/explainer/authors/script.svml) and [Main Source](https://github.com/hypit-ai/hypit/blob/main/examples/complex-explainer/productions/explainer/authors/main.svml) |
-| How do existing footage, a moving viewport and independent graphics coexist? | [Opening system and Performance Styles](https://github.com/hypit-ai/hypit/blob/main/examples/complex-explainer/packages/opening-system/README.md) |
+| How do existing footage, a moving viewport and independent graphics coexist? | [Opening system and visual presentation](https://github.com/hypit-ai/hypit/blob/main/examples/complex-explainer/packages/opening-system/README.md) |
| What belongs inside a coordinated demonstration? | [Scene map, inputs and internal modules](https://github.com/hypit-ai/hypit/blob/main/examples/complex-explainer/packages/web-scenes/README.md) |
| How can Caption stay independently editable? | [Project Caption package](https://github.com/hypit-ai/hypit/blob/main/examples/complex-explainer/packages/single-line-captions/README.md) |
diff --git a/skills/hypit/references/playbooks/formats/talking-head.md b/skills/hypit/references/playbooks/formats/talking-head.md
index b43ea61b..824f017b 100644
--- a/skills/hypit/references/playbooks/formats/talking-head.md
+++ b/skills/hypit/references/playbooks/formats/talking-head.md
@@ -71,8 +71,9 @@ the actual duration; [media preparation](../../production/media.md) explains how
align it. A Segment can contain several edited shots, Caption Cue Breaks, graphic changes and
speaking turns. Choose its boundaries from the performance it carries.
-Normalize the produced speaking media, align its own audio to its Segment, and assemble the
-SemanticTakes. Keep that performance's sound when B-roll covers its picture. Place evidence on
+Normalize the produced speaking media, align its own audio to its Segment, construct its equal-length
+Timeline Window, and project that alignment through the local domain/Window relation. Keep that performance's sound
+when B-roll covers its picture. Place evidence on
Selections and reveals on the component's declared timing inputs. A persistent board can continue
through a cut while the current portrait, evidence image and Caption change.
diff --git a/skills/hypit/references/playbooks/formats/two-person-podcast.md b/skills/hypit/references/playbooks/formats/two-person-podcast.md
index 43ebfe62..91b2eb02 100644
--- a/skills/hypit/references/playbooks/formats/two-person-podcast.md
+++ b/skills/hypit/references/playbooks/formats/two-person-podcast.md
@@ -94,7 +94,8 @@ rather than treating an existing project's Recipe as a required choice.
Use separate clips when exact scene-to-cue correspondence matters, especially in reconstruction.
Generate each within the selected model's actual range and consume only the needed section. Read
-[B-roll](../craft/b-roll.md) for source duration, `stretch`, short windows and gap-free boundaries.
+[B-roll](../craft/b-roll.md) for source duration, explicit source-time relations, short windows and
+intentional boundaries.
Host-colored Caption can clarify the speaker even over full-frame B-roll. Coordinate it with the
scene palette and product treatment; choose the colors for this pair. Judge the whole exchange for
diff --git a/skills/hypit/references/playbooks/index.md b/skills/hypit/references/playbooks/index.md
index d88f8d3d..6ea48d11 100644
--- a/skills/hypit/references/playbooks/index.md
+++ b/skills/hypit/references/playbooks/index.md
@@ -39,8 +39,8 @@ Read every craft whose question genuinely appears in the work, including questio
a Studio preview or completed Result. Repeated use of the same craft does not require rereading it
unless the decision has changed.
-For authoring those decisions, [Performance](../production/performance.md) presents current Timeline
-footage and [Media](../production/media-presentation.md) supplies independent pictures and playback.
+For authoring those decisions, [Visual Clips](../production/visual-clips.md) place footage and
+independent pictures with explicit playback.
[Media preparation](../production/media.md#keep-original-and-processed-material-explicit) owns source
processing, including transparency; [Spatial layout](../production/spatial.md) owns fitting and crop.
These choices compose according to the intended use of the material.
diff --git a/skills/hypit/references/production/audio-clips.md b/skills/hypit/references/production/audio-clips.md
new file mode 100644
index 00000000..ac0ba2ac
--- /dev/null
+++ b/skills/hypit/references/production/audio-clips.md
@@ -0,0 +1,57 @@
+# 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.
+
+## The ordinary relation is one Clip occurrence
+
+```text
+Audio Clip = normalized audio source + absolute Window + sampling + mix
+Audio Track = additive set of Audio Clips
+```
+
+```svml
+<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"
+ 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"/>
+</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.
+
+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.
+
+## Sampling and mix stay 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.
+
+`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.
+
+## Relationships spanning Clips are components
+
+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.
+
+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.
diff --git a/skills/hypit/references/production/audio-presentation.md b/skills/hypit/references/production/audio-presentation.md
deleted file mode 100644
index 903abb01..00000000
--- a/skills/hypit/references/production/audio-presentation.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# Place independent sound
-
-Read this when supplying music, ambience, narration or effects independently of placed Takes.
-[Sound](sound.md) presents audio already on the Timeline. If a narration performs the work's Script,
-prefer an audio-only SemanticTake and Sound so its words establish reusable semantic time.
-An independent audio contribution can still follow that same Script's events.
-
-## Prepare and place the source
-
-With the source, Clock, Script and Timeline already declared:
-
-```svml
-<import as="pipeline" from="@hypit/media-pipeline@1"/>
-<import as="audio" from="@hypit/audio-track@1"/>
-<pipeline:Normalize id="hit-media" source={hit-source} clock={clock}
- video="none" audio="default" span-authority="audio"/>
-<audio:Track id="effects" timeline={program.timeline}>
- <audio:Item id="reveal-hit" source={hit-media.media}
- at={story.moment.reveal} for="600ms" playback="once"
- gain="0.45" fade-in="0f" fade-out="3f"/>
-</audio:Track>
-```
-
-An Item consumes normalized audio-bearing media and a projected Window. Music can occupy a Segment
-or the program; effects can follow Moments. Shared [time forms](timing.md) also allow independent
-clock events. The Track publishes `.program` and `.audio`; select `.audio` in Film to hear it.
-An explicit Item id gives Studio a useful name. Two Items using one source remain two placements.
-
-## Choose source playback and mix
-
-`trim-start` and `trim-end` are source durations in frames, milliseconds or seconds; the end is
-exclusive. For example, `1s` to `3s` selects those two source seconds. This differs from Media Track's
-integer frame trim properties. Destination time remains the Item's Window.
-
-- `once` / `once-start` plays from the Window start; `once-end` aligns native playback to its end.
-- `loop` / `loop-start` and `loop-end` repeat with the selected alignment.
-- `stretch` retimes with pitch preserved and requires explicit `min-rate` and `max-rate` bounds.
-
-Playback expresses the intended occupancy. A long Window does not automatically loop or stretch
-a short source. The installed `@hypit/audio-track` README owns exact behavior and rate constraints.
-
-`gain` is a linear multiplier, defaulting to 1; fade durations default to `0f`. Normalization preserves
-source level. Overlapping Audio Items mix; overlapping visual Items instead compose by paint order.
-Balance music, speech, ambience and effects in the actual Film. [Sound direction](../playbooks/craft/sound-mix.md)
-owns the audible judgment, including ducking and continuity.
-
-A sound can share a semantic Moment with a reveal while remaining a separate contribution. If a
-visual component owns a coupled sound, it can publish a peer AudioTrack output; Film still selects
-that sound explicitly. Neither route requires reading another component's private state.
diff --git a/skills/hypit/references/production/authoring.md b/skills/hypit/references/production/authoring.md
index cf902b93..305b79b6 100644
--- a/skills/hypit/references/production/authoring.md
+++ b/skills/hypit/references/production/authoring.md
@@ -110,8 +110,9 @@ is also a normal Target when the user requested that deliverable or the work gen
independently now.
Every public Author Output that completes while satisfying the demanded Target is stored in that
-Build Result and can be inspected or reused later. Derived public Outputs such as a SemanticTake
-therefore remain available when a downstream Target caused them to complete.
+Build Result and can be inspected or reused later. Derived public Outputs such as normalized media,
+a local temporal domain or alignment evidence therefore remain available when a downstream Target
+caused them to complete.
The Author Graph supplies primary Candidates. A Run may explicitly select another compatible
Candidate for a Logical Output:
@@ -168,26 +169,26 @@ submitting the same paid media requests again. The following examples locate the
| Current change | Keep through Candidates | Recompute or request |
| --- | --- | --- |
-| Caption appearance, MG, an Effect or composition changes | Existing media and SemanticTakes whose Script identities and timing still apply | The changed visual systems and render |
-| Moment/Selection placement changes, with unchanged spoken tokens and Take identities | The accepted SemanticTakes and other material | Current Script references, their projections and presentation |
-| Cue grouping, word attributes or display-only Dual wording changes without changing speech tokens | The accepted SemanticTakes | The current CaptionDocument and its presentation |
-| Take placement or complete Timeline extent changes | The prepared local Takes | Timeline assembly, all affected projections and presentation |
+| Caption appearance, MG, an Effect or composition changes | Existing normalized media, local domains and alignment evidence that still apply | The changed visual systems and render |
+| Moment/Selection placement changes, with unchanged spoken tokens and alignment identities | The accepted media, local domains and alignment evidence | Current Script references, their projections and presentation |
+| Cue grouping, word attributes or display-only Dual wording changes without changing speech tokens | The accepted media, local domains and alignment evidence | The current CaptionDocument and its presentation |
+| Temporal placement or complete Timeline extent changes | The normalized media, local domains and alignment evidence | Timeline assembly, all affected projections, placed media and presentation |
| Only some B-roll images must change | The existing performance, voice and all other still-useful media | The deliberately replaced images and their downstream composition |
| The presenter changes while the spoken argument still fits | Unaffected B-roll, icons, music and other media that still serve the target | The new presenter images, affected performances, their normalization and semantic timing, and downstream composition |
| A new product changes the demonstration or claims | Views and media whose content still fits the new Treatment | The affected product views, performance, Script-dependent timing and visual treatment |
| The same video needs different normalization or semantic timing | Its generated video Output, or normalized media when that still applies | The affected normalization or alignment and downstream consumers |
-| New spoken wording requires a new performance | Unaffected Takes and other still-useful inputs | The changed performance and the timing derived from it |
+| New spoken wording requires a new performance | Unaffected media and other still-useful inputs | The changed performance and the timing derived from it |
Choose an Output upstream of the work being changed, with the same nominal Type and the intended
-creative meaning. An unchanged SemanticTake can preserve both media and alignment. It is valid only
-while its Narrative, Segment, token and anchor identities and timing still describe the current
-Script and media. A Script edit does not automatically invalidate every Take; inspect what changed.
-Markers select existing token/Segment anchors. Moving a marker can therefore reuse accepted timing
-when those anchors and spoken tokens remain the same; no acoustic measurement is needed merely
-because a cue now follows another word. Changing spoken text, tokenization, Segment identity or the
-source performance requires a fresh judgment about the affected Take. Keep the media upstream when
-it still fits and let the required preparation recompute. No reuse selection automatically adapts an
-old Take to new speech.
+creative meaning. Media, its local temporal domain and its NarrativeAlignment are independent reusable
+facts; retain exactly the ones that still apply. Alignment evidence is valid only while its Narrative,
+Segment, token and anchor identities and timing still describe the current Script and media. A Script
+edit does not automatically invalidate all media or alignment; inspect what changed. Markers select
+existing token/Segment anchors. Moving a marker can therefore reuse accepted alignment when those
+anchors and spoken tokens remain the same; no acoustic measurement is needed merely because a cue now
+follows another word. Changing spoken text, tokenization, Segment identity or the source performance
+requires a fresh judgment about the affected alignment. Keep upstream media when it still fits and let
+only the required preparation recompute. No reuse selection silently adapts old evidence to new speech.
Do not satisfy a changed Track or final composition with its old rendered Output, which would hide
the current edit. Type compatibility alone cannot establish that an old performance or timing still fits.
diff --git a/skills/hypit/references/production/browser-capture.md b/skills/hypit/references/production/browser-capture.md
index 3d7f4b69..625f86f0 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](media-presentation.md#keep-display-time-and-source-playback-distinct) and the Script's
+[Media presentation](visual-clips.md#keep-display-time-and-source-playback-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/builds.md b/skills/hypit/references/production/builds.md
index 37f6b263..f4b51bf3 100644
--- a/skills/hypit/references/production/builds.md
+++ b/skills/hypit/references/production/builds.md
@@ -11,7 +11,7 @@ how the selected graph becomes a Build, and [rendering](rendering.md) covers who
For a revision, identify the relevant Run and its completed Outputs, then preserve the still-useful
ones with `build-record` and `satisfy`. Keep unrelated Candidate selections. [Authoring](authoring.md#reuse-produced-work-explicitly)
-explains which media or SemanticTake Output to keep without freezing the downstream edit. A failed
+explains which media, local-domain or alignment Output to keep without freezing the downstream edit. A failed
Build can still supply completed Outputs; a missing exported file is not evidence of missing media.
If the CLI or observation tool loses its reply while submitting or following a Build, inspect the
@@ -66,8 +66,8 @@ from the earlier attempt in its Run.
When a usable receipt does exist and gives access to a generated asset, the Agent can retrieve that
asset as an ordinary project file and select it with `file` and `satisfy` in the new Run. This supplies
-the file Output; downstream preparation and alignment still run when needed. A completed SemanticTake
-can instead be reused directly through its existing Result Output.
+the file Output; downstream preparation and alignment still run when needed. Completed normalized
+media, local-domain and alignment Outputs can instead be reused independently through the existing Result.
Use `status <build-id> --verbose` for task IDs, Endpoints and progress. Use
`inspect <build-id> --verbose --json` for the Result's full retained execution records, including
diff --git a/skills/hypit/references/production/caption-authoring.md b/skills/hypit/references/production/caption-authoring.md
index 44c5e50c..09117ee9 100644
--- a/skills/hypit/references/production/caption-authoring.md
+++ b/skills/hypit/references/production/caption-authoring.md
@@ -25,7 +25,7 @@ to a Script Moment.
## Own the visual relationship
-Performance presents placed footage; Media supplies independent pictures. A scene component can
+Visual Clip presents placed footage; Visual Clips supply independent pictures. A scene component can
coordinate either with diagrams or other graphics. Fine and custom Caption families have the same relationship. Their shared input is the
authored speech and its semantic timing; the implementation owns the spatial structure and motion.
@@ -48,7 +48,8 @@ and evaluate its state at the requested frame. Keep separately useful overlays a
```text
Script → CaptionDocument (displayed words, Cue breaks and word attributes)
-CaptionDocument + Timeline → complete timed Cues and original word times
+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
```
@@ -65,12 +66,12 @@ Script document types. A family Track accepts `document`, `timeline` and ordered
<keyword:Track id="captions" document={story.caption} timeline={program.timeline}>
<keyword:Use style={base-style}/>
<keyword:Use role="GUEST" style={guest-style}/>
- <keyword:Use during={story.selection.punchline} style={punchline-style}/>
+ <keyword:Use during={story-time.punchline} style={punchline-style}/>
</keyword:Track>
```
-These names assume the project family and its Styles have been declared. Reuse the common time
-projection helpers for `during`, `at`/`for`, `until`/`for` and `start`/`end`. A Use has the same
+These names assume the project family and its Styles have been declared. Reuse the common absolute
+time helpers for `during`, or exactly two of `from`, `until` and `for`. A Use has the same
meaning regardless of the family. `role` filters whose content it presents within that window.
For a keyword layout, Script can mark `useful{emphasis}`. The family reads that attribute from the
@@ -117,7 +118,7 @@ retains all Cues regardless of Style. Empty or uncovered time naturally produces
## Give Style, layout and rendering clear owners
The Style Surface validates a Recipe and exact font references, then emits the common Caption Style
-shape with the new family's name and parameters. The Track Surface accepts the document,
+shape with the new family's name and parameters. The Caption Surface accepts the document,
Timeline and timed Use children; its Fragment assembles the Uses, performs the common timing join,
and runs its own schedule and render operations. Register the new family's Producers and any new schedule Type in its own package.
@@ -134,7 +135,7 @@ family handles its own layouts. Each Track is independent, so multiple Tracks ca
show captions together or use complementary coverage. Mixed-family rendering, if useful, belongs
to the component that implements it.
-If this family supports spatial tracking, take an explicit RegionTimeline and map it into the actual
+If this family supports spatial tracking, take an explicit Region Track and map it into the actual
composition. Define subject matching and absent-region behavior. Detection belongs to the measurement
step described in [Caption tracking](../playbooks/craft/caption-tracking.md), not to this renderer.
diff --git a/skills/hypit/references/production/caption-presentation.md b/skills/hypit/references/production/caption-presentation.md
index 3d5477c1..4e35fc09 100644
--- a/skills/hypit/references/production/caption-presentation.md
+++ b/skills/hypit/references/production/caption-presentation.md
@@ -5,18 +5,21 @@ Read this to apply subtitle treatments, change them during a passage, or hide th
[Caption authoring](caption-authoring.md) explains creating a new family.
**Script organizes content; Use organizes presentation in time.** `||` determines which words belong
-together. The Track joins `document={story.caption}` to the placed `timeline`, preserving displayed
-text and pronunciation associations. Each Use selects a complete Style inside a time window.
+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.
```svml
<caption:Hidden id="hidden"/>
-<caption-fine:Track id="captions" document={story.caption} timeline={program.timeline}>
+<narrative-caption:Timing id="story-captions" document={story.caption}
+ binding={story.caption-binding} projection={story-time.projection}/>
+<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={story.selection.answer} style={answer-style}/>
- <caption-fine:Use during={story.selection.demonstration} style={hidden}/>
- <caption-fine:Use at={story.moment.key} for="2s" style={impact-style}/>
-</caption-fine:Track>
+ <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:Caption>
```
Styles are declared by the chosen family. Fine Styles take a Recipe and exact fonts. A new structural
@@ -27,11 +30,11 @@ caption can use a project family with its own layout and behavior.
| Intent | Use |
| --- | --- |
| A treatment across the whole Timeline | `style={base}` with no time attributes |
-| Follow a semantic passage | `during={story.selection.answer}` |
-| Follow a placed Segment | `during={story.segment.answer}` |
-| Start at a meaningful word, for a fixed duration | `at={story.moment.key} for="2s"` |
-| End at a meaningful event | `until={story.moment.key} for="12f"` |
-| Explicit window | `start="8s" end="10s"` |
+| 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"` |
| A particular speaker | Add `role="GUEST"` to any of these |
[Timing](timing.md) owns the shared expressions and semantic references.
@@ -43,7 +46,7 @@ The last matching Use in Source order wins locally. Each match replaces the whol
are not merged. A hidden Use clears this Track's subtitle presentation throughout that window,
including neighboring Cue lead/tail. Later Uses can restore a smaller interval. Audio and content
stay unchanged. With no matching Use, nothing is drawn. With no subtitle content, a Use has nothing
-to draw. Independent Caption Tracks can intentionally show multiple presentations at the same time.
+to draw. Independent Caption components can intentionally show multiple presentations at the same time.
## A style change can happen inside a Cue
diff --git a/skills/hypit/references/production/component-design.md b/skills/hypit/references/production/component-design.md
index 43e80d1a..66f32289 100644
--- a/skills/hypit/references/production/component-design.md
+++ b/skills/hypit/references/production/component-design.md
@@ -29,7 +29,7 @@ authored identity while its state develops. Let shared behavior define the unit.
A performance moving from full screen into a side viewport and a diagram filling the released space
can share one component. It owns their relative layout, overlap, masking and coordinated motion.
A-roll supplies the performed passage; visual ownership follows the behavior being designed.
-Existing footage can use [Performance Styles](performance.md); independent assets use Media. A
+Existing footage and independent assets can both use [Visual Clips](visual-clips.md). A
one-off scene is a useful component too. Caption and independent overlays can remain separate.
Decompose a scene further where its parts have meaningful independent responsibilities. Keep
@@ -105,10 +105,11 @@ relationship among words and graphics. Both consume Script wording and semantic
behavior can keep these visuals together; [Caption authoring](caption-authoring.md) explains the
specialized text inputs and the same freedom to compose.
-Give a reusable scene the prepared performance, its outer Window and the Moment that changes its
-layout through the Timeline and shared temporal projections. Replacing a product or rewriting the
-Script then changes content and semantic anchors while preserving the behavior. The final frame
-positions come from the placed Takes.
+Give a reusable scene explicit normalized media sources, their exact absolute Windows, its outer
+Window and the Moment that changes
+its layout through the Timeline and shared temporal projections. Replacing a product or rewriting the
+Script then changes content and semantic anchors while preserving the behavior. Source sampling comes
+from each source Window; final geometry comes from the component's explicit picture-plane Frames.
The repository's [video examples](https://github.com/hypit-ai/hypit/tree/main/examples) show different
applications: a persistent ranking board, related podcast views, a shared interview encounter and
diff --git a/skills/hypit/references/production/component-visuals.md b/skills/hypit/references/production/component-visuals.md
index d0201be1..677b9349 100644
--- a/skills/hypit/references/production/component-visuals.md
+++ b/skills/hypit/references/production/component-visuals.md
@@ -47,16 +47,16 @@ and expose only the inputs the production needs.
The root uses Canvas coordinates. The text child uses the root's local coordinates, so padding is
added once. When a component computes child geometry in Canvas space, subtract the parent's origin
before writing child `left` and `top`.
-Element `order` values are distinct within the Present; `stacking.order` separately places that
-whole Present among the composition's other appearances.
+Present `order` is local to its owning Visual Track, while `z` places that Present in the final Film
+paint order. Element `order` is local again to the containing Present.
The function is the drawing part of a package. Connect it to a Producer with matching typed inputs,
then publish the Track through the Fragment and Surface as described in
[Track authoring](track-authoring.md#connect-the-implementation-at-its-real-boundaries). Surface outputs
map the Fragment's export name to a public Source name such as `answers.track`.
-Use `programSpaceFrameCount` from `@hypit/hypit/program-space` for the full program's frame count and
-`assertVisualTrackIdentity(track, space)` to check a produced Track against that space. Direct seeking
+Use `timelineFrameCount` from `@hypit/hypit/timeline` for the full Timeline's frame count and
+`assertVisualTrackIdentity(track, timeline)` to check a produced Track against it. Direct seeking
and range rendering evaluate the same declared keyframes at the requested frame.
## Elements, fonts and other assets
@@ -73,7 +73,7 @@ hypit vocabulary --visual text
Visual styles and Motion use the installed CSS-shaped property vocabulary; query the relevant visual
shapes above for their supported values. Motion uses frame-indexed keyframes. Media sampling separately
describes which source frame to show at each part of a Present; it is needed for timed video playback,
-trims, loops and holds. Existing Media Track is useful when that is the whole role.
+trims, loops and holds. A Visual Clip is useful when that is the whole role.
Carry asset and font references through declared inputs. Source assets can be resolved at the
Surface's asset boundary; generated media remains a graph reference until its Producer runs.
@@ -128,12 +128,11 @@ video sampling and font handling while participating in the program's HTML layou
used by the program belong in its `artifacts` list; `hyperframesResourceUri` supplies their resource
URLs. The rendering environment materializes those references.
-For a placed performance, `projectTimelineMedia(timeline, window.span)` from
-`@hypit/hypit/timeline` returns each intersecting Take's prepared media, program span and source
-span. Subtract the containing Present's start to obtain Present-local video sampling intervals
-(when that Present uses the outer Window as its span, subtract the Window start). Preserve
-the returned source offset: moving or reframing a video changes its presentation while playback
-continues from the same place. A separate Sound presentation can continue the existing audio in Film.
+For time-bearing footage, give the component ordinary normalized media, the absolute Window it needs
+and an explicit sampling choice. Intersect that Window with the containing Present, then derive the
+matching source-frame span from the authored sampling relation. Subtract the Present's start to obtain
+Present-local video sampling intervals. Moving or reframing a video does not itself choose or restart
+playback. The same media can independently feed a peer Audio Clip when the Film should retain its sound.
Project each independently meaningful event before rendering. Convert its program frame to the
containing Present's local frame once, then animate relative to that event. Keep source sampling
@@ -141,9 +140,9 @@ based on the returned source span; neither the event's local offset nor the view
replaces it. [Component design](component-design.md#let-meaning-drive-the-behavior) distinguishes these
inputs from internal motion details.
-A reusable scene might expose `during={story.selection.explanation}` for its lifetime and
-`reveal={story.moment.demonstrate}` for its layout change. The Surface projects these independently;
-the Producer receives a Window and an Instant. The installed Distribution's
+A reusable scene might expose `during={story-time.explanation}` for its lifetime and
+`reveal={story-time.demonstrate}` for its layout change. An upstream Narrative projector publishes
+these independently; the Producer receives a Window and an Instant. The installed Distribution's
`examples/semantic-composition/packages/responsive-explainer` shows this complete package: video
moves from full screen to a side viewport while a diagram enters, with Caption available as a peer.
diff --git a/skills/hypit/references/production/examples/detail.svrun b/skills/hypit/references/production/examples/detail.svrun
index b5c847b7..756c2719 100644
--- a/skills/hypit/references/production/examples/detail.svrun
+++ b/skills/hypit/references/production/examples/detail.svrun
@@ -2,7 +2,11 @@
<svrun version="1">
<author source="./production.svml"/>
<target output="detail.video"/>
- <!-- Replace the Build id with the Result containing this production's Take. -->
- <build-record id="kept-take" build="bld_..." output="opening-semantic.take"/>
- <satisfy output="opening-semantic.take" candidate="kept-take"/>
+ <!-- Replace the Build id with the Result containing this production's prepared material. -->
+ <build-record id="kept-media" build="bld_..." output="performance-media.media"/>
+ <build-record id="kept-domain" build="bld_..." output="performance-media.domain"/>
+ <build-record id="kept-alignment" build="bld_..." output="opening-alignment.alignment"/>
+ <satisfy output="performance-media.media" candidate="kept-media"/>
+ <satisfy output="performance-media.domain" candidate="kept-domain"/>
+ <satisfy output="opening-alignment.alignment" candidate="kept-alignment"/>
</svrun>
diff --git a/skills/hypit/references/production/examples/look.svs b/skills/hypit/references/production/examples/look.svs
index 67886058..cd3f1682 100644
--- a/skills/hypit/references/production/examples/look.svs
+++ b/skills/hypit/references/production/examples/look.svs
@@ -1,6 +1,5 @@
<?svml using="@hypit/svs@1"?>
<sheet version="1">
- media.performance { stack-order: 0; fit: cover; }
text.title { size: 54; weight: 700; stack-order: 20; }
film.main { background: #18212A; }
</sheet>
diff --git a/skills/hypit/references/production/examples/material.svrun b/skills/hypit/references/production/examples/material.svrun
index cb2236ce..e62a12e7 100644
--- a/skills/hypit/references/production/examples/material.svrun
+++ b/skills/hypit/references/production/examples/material.svrun
@@ -1,5 +1,5 @@
<?svml using="@hypit/run-markup@1"?>
<svrun version="1">
<author source="./production.svml"/>
- <target output="opening-semantic.take"/>
+ <target output="opening-alignment.alignment"/>
</svrun>
diff --git a/skills/hypit/references/production/examples/production.svml b/skills/hypit/references/production/examples/production.svml
index 628c132b..1986d3ed 100644
--- a/skills/hypit/references/production/examples/production.svml
+++ b/skills/hypit/references/production/examples/production.svml
@@ -1,17 +1,18 @@
<?svml using="@hypit/markup@1"?>
<svml>
- <import as="sound" from="@hypit/sound@1"/>
- <import as="performance" from="@hypit/performance@1"/>
+ <import as="audio" from="@hypit/audio-track@1"/>
+ <import as="visual" from="@hypit/visual-track@1"/>
<import from="@hypit/script@1"/>
<import as="text" from="@hypit/text@1"/>
<import as="seedance" from="@hypit/seedance@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
+ <import as="semantic" from="@hypit/narrative-temporal@1"/>
+ <import as="media" from="@hypit/media@1"/>
<import as="time" from="@hypit/timeline-author@1"/>
<import as="space" from="@hypit/spatial@1"/>
- <import as="program" from="@hypit/program-space@1"/>
<import as="fonts" from="@hypit/fonts-open@1"/>
- <import as="typo" from="@hypit/typography-track@1"/>
+ <import as="typo" from="@hypit/text-fine@1"/>
<import as="film" from="@hypit/film@1"/>
<import as="render" from="@hypit/render-hyperframes@1"/>
<import as="look" source="./look.svs"/>
@@ -21,10 +22,10 @@
<opening><HOST>Here is @{proof}the useful part.@{/proof}</opening>
</script>
<space:Canvas id="canvas" width="720" height="1280"/>
- <program:Clock id="clock" frame-rate="30"/>
- <space:Frame id="full" within={canvas}
+ <time:Clock id="clock" frame-rate="30"/>
+ <space:Frame id="full" within={canvas.bounds}
left="0%" top="0%" right="100%" bottom="100%"/>
- <space:Frame id="title-frame" within={canvas}
+ <space:Frame id="title-frame" within={canvas.bounds}
left="8%" top="12%" right="92%" bottom="30%"/>
<text:Value id="direction">
@@ -39,33 +40,33 @@
duration="5" aspect-ratio="9:16" generate-audio="true"/>
<pipeline:Normalize id="performance-media" source={performance.video} clock={clock}
video="primary-moving" audio="default" span-authority="video"/>
- <whisperx:SemanticTake id="opening-semantic" narrative={story}
- segment={story.segment.opening} media={performance-media.media} language="en"/>
- <time:Timeline id="speech" clock={clock}>
- <time:Take source={opening-semantic.take}/>
+ <whisperx:Alignment id="opening-alignment" narrative={story}
+ segment={story.segment.opening} media={performance-media.media}
+ domain={performance-media.domain} language="en"/>
+ <time:Timeline id="speech" clock={clock} end="opening.end">
+ <time:Window id="opening" from="start" for={performance-media.extent}/>
+ <time:Window id="proof-label" from="opening.start+2s" for="2s"/>
</time:Timeline>
-
- <sound:Style id="speech-sound-style"/>
- <sound:Track id="speech-sound" timeline={speech.timeline}>
- <sound:Use style={speech-sound-style}/>
- </sound:Track>
- <performance:Style id="speech-picture-style" frame={full} appearance={look.media.performance}/>
- <performance:Track id="speech-picture" timeline={speech.timeline} canvas={canvas}>
- <performance:Use style={speech-picture-style} during="program"/>
- </performance:Track>
+ <semantic:Projection id="story-time" narrative={story} timeline={speech.timeline}>
+ <semantic:Map alignment={opening-alignment.alignment} domain={performance-media.domain} window={speech.opening}/>
+ </semantic:Projection>
+ <audio:Track id="speech-sound" timeline={speech.timeline}>
+ <audio:Clip id="opening-source" source={performance-media.media} during={speech.opening}/>
+ </audio:Track>
+ <visual:Track id="speech-picture" timeline={speech.timeline}>
+ <visual:Clip id="opening-source" media={performance-media.media} during={speech.opening} frame={full} z="10" fit="cover"/>
+ </visual:Track>
<fonts:Stack id="title-font" family="inter" weight="700" style="normal" emoji="color"/>
<typo:Style id="title-style" recipe={look.text.title} font={title-font}>
<typo:Fill color="#F1E7D8"/>
</typo:Style>
- <typo:Track id="titles" timeline={speech.timeline}>
- <typo:Area id="proof-label" placement={title-frame} style={title-style}
- during={story.selection.proof}>The useful part</typo:Area>
- </typo:Track>
- <film:Film id="main" canvas={canvas} timeline={speech.timeline} appearance={look.film.main}>
+ <typo:Flow id="proof-label" timeline={speech.timeline} within={title-frame}
+ style={title-style} during={speech.proof-label}>The useful part</typo:Flow>
+ <film:Film id="main" canvas={canvas.canvas} timeline={speech.timeline} appearance={look.film.main}>
<film:Track source={speech-picture.visual}/>
<film:Track source={speech-sound.audio}/>
- <film:Track source={titles.track}/>
+ <film:Track source={proof-label.visual}/>
</film:Film>
<render:Video id="final" composition={main.composition} timeline={speech.timeline}/>
<render:Video id="detail" composition={main.composition} timeline={speech.timeline}
diff --git a/skills/hypit/references/production/examples/visuals.ts b/skills/hypit/references/production/examples/visuals.ts
index ab47e791..9fe12241 100644
--- a/skills/hypit/references/production/examples/visuals.ts
+++ b/skills/hypit/references/production/examples/visuals.ts
@@ -1,13 +1,13 @@
import { sealVisualTrack } from "@hypit/hypit/composition";
import type { FrameSpan } from "@hypit/hypit/composition";
import type { FontArtifactRef } from "@hypit/hypit/media";
-import type { ProgramSpace } from "@hypit/hypit/program-space";
+import type { Timeline } from "@hypit/hypit/timeline";
import { VISUAL_IR_V1 } from "@hypit/hypit/visual-ir";
// The caller supplies its projected Window, resolved Frame and selected font faces.
export function renderCard(input: {
id: string;
- space: ProgramSpace;
+ timeline: Timeline;
span: FrameSpan;
frame: { x: number; y: number; width: number; height: number };
text: string;
@@ -24,13 +24,14 @@ export function renderCard(input: {
const entranceEnd = Math.min(input.entranceFrames, length - 1);
return sealVisualTrack({
id: input.id,
- programSpaceId: input.space.id,
+ timelineId: input.timeline.id,
visualIr: VISUAL_IR_V1,
presents: [{
id: `${input.id}-present`,
subjectId: input.id,
span: input.span,
- stacking: { order: input.layer, tieBreak: input.id },
+ order: 0,
+ z: input.layer,
elements: [{
kind: "box", id: root, order: 0,
style: [
diff --git a/skills/hypit/references/production/fonts-and-text.md b/skills/hypit/references/production/fonts-and-text.md
index 920e2cdb..b29e96ba 100644
--- a/skills/hypit/references/production/fonts-and-text.md
+++ b/skills/hypit/references/production/fonts-and-text.md
@@ -91,48 +91,50 @@ The following excerpt assumes the named Fonts, layout Frames, Timeline and Recip
```svml
<import as="copy" from="@hypit/text@1"/>
-<import as="typo" from="@hypit/typography-track@1"/>
+<import as="typo" from="@hypit/text-fine@1"/>
<typo:Style id="headline-style" recipe={look.text.title} font={headline-font}>
<typo:Fill color="#F1E7D8"/>
</typo:Style>
<copy:Value id="headline">A useful idea, clearly shown.</copy:Value>
-<typo:Track id="titles" timeline={speech.timeline}>
- <typo:Area id="opening-title" content={headline} placement={title-frame}
- style={headline-style} during={story.selection.proof}/>
-</typo:Track>
+<typo:Flow id="opening-title" timeline={speech.timeline} content={headline}
+ within={title-frame} style={headline-style} z="20" align="center"
+ during={speech.opening}/>
```
-Include `titles.track` in Film. The Style supplies typography, Paint and layer order; the item
-supplies content, placement and time. Use `during="program"` for a title that lasts throughout the
-program, or the component's declared Window forms for a shorter appearance.
+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
+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
-`text.title { size: 54; weight: 400; stack-order: 20; }`, matching the selected headline face.
+`text.title { size: 54; weight: 400; }`, matching the selected headline face. The direct `z="20"`
+remains visible at the occurrence where it affects composition.
| Placement | Input and use |
| --- | --- |
| Point | A SpatialPoint anchoring text whose box follows its content |
-| Area | A SpatialFrame for wrapping and fitting text in a bounded region |
+| Flow | A SpatialFrame for wrapping and fitting text in a bounded region |
| Path | A SpatialPath for text following an authored curve |
-Query `hypit vocabulary @hypit/typography-track --tag Style` for the Recipe properties and
-`--tag Track` for placement, content and motion forms. [Spatial layout](spatial.md) explains the
+Query `hypit vocabulary @hypit/text-fine --tag Style` for the Recipe properties and
+`--tag Flow`, `--tag Point` or `--tag Path` for placement, content and motion forms. [Spatial layout](spatial.md) explains the
geometry these inputs carry.
## Rich text and motion
-An item can take graph Text through `content={...}`, or own an inline document with `typo:P`,
-`typo:Span` and `typo:Break`. For example, inside an Area:
+An occurrence can take graph Text through `content={...}`, or own an inline document with `typo:P`,
+`typo:Span` and `typo:Break`. For example, inside a Flow:
```svml
<typo:P>Made for <typo:Span style={accent-style}>this moment</typo:Span>.</typo:P>
```
A paragraph or Span Style replaces that run's complete typography and Paint, including its font
-and size. The outer item continues to supply placement and layer order.
+and size. The outer occurrence continues to supply placement and layer order.
-Typography Motion can act on the item or stagger words and graphemes. Use the installed Motion
+Typography Motion can act on the occurrence or stagger words and graphemes. Use the installed Motion
vocabulary for its frame offsets and normalized sequence positions. For a new speech-text layout
or scheduling relationship, [Caption authoring](caption-authoring.md) explains creating a family
that consumes the existing Caption document and semantic timing.
diff --git a/skills/hypit/references/production/image-operations.md b/skills/hypit/references/production/image-operations.md
index c8d496c0..d079b712 100644
--- a/skills/hypit/references/production/image-operations.md
+++ b/skills/hypit/references/production/image-operations.md
@@ -5,7 +5,7 @@ cut out before it becomes a model reference or a Track item. [Image direction](.
owns what the image should communicate; [spatial layout](spatial.md) owns Canvas, Frame and fit.
An image operation publishes another ordinary image Output. The resulting image can feed Seedance,
-a Media Track, another image operation, or any compatible project component. The operation belongs
+a Visual Clip, another image operation, or any compatible project component. The operation belongs
in Source when that transformation is part of the reproducible production relationship.
## Flatten a fixed still-image arrangement
@@ -21,12 +21,12 @@ Declare the Canvas and every rectangular destination explicitly:
<import as="compose" from="@hypit/image-compose@1"/>
<space:Canvas id="comparison-canvas" width="2048" height="1024"/>
-<space:Frame id="before-panel" within={comparison-canvas}
+<space:Frame id="before-panel" within={comparison-canvas.bounds}
left="0%" top="0%" right="50%" bottom="100%"/>
-<space:Frame id="after-panel" within={comparison-canvas}
+<space:Frame id="after-panel" within={comparison-canvas.bounds}
left="50%" top="0%" right="100%" bottom="100%"/>
-<compose:Image id="comparison" canvas={comparison-canvas} background="#EEEAE2FF">
+<compose:Image id="comparison" canvas={comparison-canvas.canvas} background="#EEEAE2FF">
<compose:Layer source={before.image} frame={before-panel} fit="contain"/>
<compose:Layer source={after.image} frame={after-panel} fit="contain"/>
</compose:Image>
@@ -77,7 +77,7 @@ Use Background Removal when the next composition needs a still subject without i
<remove:Background id="presenter-cutout" source={portrait.image}/>
```
-`{presenter-cutout.image}` is an image with transparency, ready for a Media Track, image composition,
+`{presenter-cutout.image}` is an image with transparency, ready for a Visual Clip, image composition,
or another compatible consumer. The Runtime Profile chooses the Endpoint that performs the removal;
the Source records only the requested visual relationship.
@@ -93,7 +93,7 @@ explains video matting, operation order, retained originals and the processed pi
## Keep operation and presentation distinct
-Composing or correcting image bytes changes the reusable image itself. A Media Track instead places
+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
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 dab351d4..3ef5d83a 100644
--- a/skills/hypit/references/production/index.md
+++ b/skills/hypit/references/production/index.md
@@ -4,9 +4,10 @@ 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 → prepared
-SemanticTakes → Timeline. Performance and Sound present the selected footage and audio; 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, 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 a standalone asset edit, follow the actual material operation and deliver its output.
## Express the work
@@ -24,8 +25,8 @@ For a standalone asset edit, follow the actual material operation and deliver it
| Current question | Owner |
| --- | --- |
-| Files, generated/reused outputs, stream selection, normalization, semantic preparation or processed variants | [Media preparation](media.md) |
-| Take placement, gaps, overlap and complete duration | [Timeline](timeline.md) |
+| Files, generated/reused outputs, stream selection, normalization, local domains, semantic alignment or processed variants | [Media preparation](media.md) |
+| Timeline end, Instants, Windows, Extents, Placements, gaps and overlap | [Timeline](timeline.md) |
| Semantic events, clock positions, offsets, durations and timing edits | [Timing](timing.md) |
| Canvas, destination Frames, source extents, fit, crop and coordinates | [Spatial layout](spatial.md) |
| Download source footage | [Video downloads](video-downloads.md) |
@@ -39,10 +40,8 @@ A-roll-only or B-roll-only.
| Current question | Owner |
| --- | --- |
-| Present existing Timeline footage; change its treatment while playback continues | [Performance](performance.md) |
-| Place independent images, video or surfaces; choose sampling and replacements | [Media presentation](media-presentation.md) |
-| Present existing Timeline audio; silence, gain or explicit source blends | [Sound](sound.md) |
-| Place independent music, narration, ambience or effects | [Audio presentation](audio-presentation.md) |
+| Place footage or independent images/video; choose treatment and sampling, or identify coordinated behavior that needs a component | [Visual Track](visual-clips.md) |
+| Present placed performance audio or independent music, narration, ambience and effects | [Audio Track](audio-clips.md) |
| Present Script words with broad/local Styles or speaker filters | [Caption presentation](caption-presentation.md) |
| Exact fonts, multilingual text, Emoji and independent Typography | [Fonts and text](fonts-and-text.md) |
diff --git a/skills/hypit/references/production/media-presentation.md b/skills/hypit/references/production/media-presentation.md
deleted file mode 100644
index 3cb89ec6..00000000
--- a/skills/hypit/references/production/media-presentation.md
+++ /dev/null
@@ -1,111 +0,0 @@
-# Present independent images, video and surfaces
-
-Read this when explicitly supplying picture content and arranging its appearance or playback.
-Use [Performance](performance.md) for footage and source positions already established by Timeline.
-The distinction is content ownership, not whether the picture contains a person, covers the frame,
-or has transparency. [Media preparation](media.md) owns the incoming values.
-
-## Supply a source and its destination
-
-With the named assets, Timeline, Canvas, Frames and Recipes declared:
-
-```svml
-<import as="media-track" from="@hypit/media-track@1"/>
-<media-track:Track id="evidence" timeline={program.timeline} canvas={canvas}>
- <media-track:Item id="photo" image={product} extent={product-extent}
- frame={detail-frame} during={story.selection.example} appearance={look.media.still}/>
- <media-track:Item id="demo" media={demo-media.media}
- frame={detail-frame} during={story.selection.proof} appearance={look.media.clip}/>
-</media-track:Track>
-```
-
-Each Item takes one direct source form: `image` with its actual `extent`, prepared `media`, or a
-compositable `surface`. The current Surface takes no raw `video` attribute. Generated and file-backed
-assets use the same inputs once they have the required Type. A still image needs no video conversion;
-its Item supplies the display duration. Code-authored graphics can publish their own Track directly.
-
-`frame` places the destination on the Canvas. `appearance` supplies fitting, clipping, decoration,
-source sampling and required `stack-order`. [Spatial layout](spatial.md) explains fitting the source's
-real extent into that Frame. Independent Items may overlap; a full-frame Item is also ordinary Media.
-
-## Keep display time and source playback distinct
-
-An Item's Window says when it is active. It can follow a Selection, Segment, Moment plus duration,
-or an authored interval through the shared [time forms](timing.md). Its source sampling separately
-says which frames to show. A semantic Window does not automatically inherit a Take's source offset.
-
-For moving media, choose playback from the intended result:
-
-| Intended behavior | Appearance `playback` |
-| --- | --- |
-| Play from the start at native speed, then expose the lower picture when exhausted | `once-start` (default) |
-| Align native playback to the Window end | `once-end` |
-| Hold the ending or beginning picture over excess time | `hold-start` / `hold-end` |
-| Repeat at native speed with start/end alignment | `loop-start` / `loop-end` |
-| Fit the selected source duration into the Window by retiming | `stretch` |
-
-`trim-start` and `trim-end` select a pair of integer source-frame boundaries, with an exclusive end.
-Omit both for the whole source. Under native playback, prepared media uses the Timeline's frame rate.
-A shorter Window can truncate a longer clip; extending the Window does not extend the source.
-Choose a hold, loop or retime only when that behavior serves the picture.
-
-Durationless images reject playback and trim options. Their appearance Window is sufficient.
-A surface's preparation supplies any frame information; its installed vocabulary describes the
-applicable sampling. The `@hypit/media-track` README owns exact mode and boundary rules.
-
-For example, independently replaying footage on a spoken claim can intentionally start that footage
-from its beginning. Presenting the speaker continuously midway through a placed Take should instead
-retain the Timeline source mapping through Performance or a project scene.
-
-## Coordinate layers and replacements
-
-An Item can declare ordered `Paint` and sampled `Layer` children instead of one direct source.
-The Item owns the outer Frame, clip, border and motion; each sampled Layer has its own fit and
-picture treatment. Use this when the parts make one framed unit. Separate Items own independent
-placement. A richer scene can own further shared behavior in a [project component](component-design.md).
-
-Use a Sequence when content replaces content in one visual slot:
-
-```svml
-<media-track:Track id="cards" timeline={program.timeline} canvas={canvas}>
- <media-track:Sequence id="steps" frame={card-frame} appearance={look.media.card}
- until={story.selection.demo} until-boundary="end">
- <media-track:Member id="first" image={first-image} extent={card-extent}
- at={story.moment.first}/>
- <media-track:Member id="second" image={second-image} extent={card-extent}
- at={story.moment.second}/>
- <media-track:Handoff id="replace" from="first" transition={look.transition.cards}/>
- </media-track:Sequence>
-</media-track:Track>
-```
-
-Members have ordered activation Instants and the Sequence has a terminal Instant. Each adjacent
-pair declares a Handoff, including a cut. `from` names the outgoing Member; the next Member is its
-successor. Transition duration and boundary ratio shape the handoff around the logical event;
-they do not relocate that event. The Sequence retains the shared outer geometry as its contents change.
-Query the selected package for its exact Layer, Member, Sampling and Handoff forms.
-
-## Move the presentation or sample the picture
-
-A `motion` Recipe moves or fades the framed unit. `Sampling` children pan, zoom or rotate the fitted
-picture inside that frame. A still can receive the same spatial sampling motion. [Spatial layout](spatial.md#move-the-frame-or-move-its-contents)
-shows the distinction and an example.
-
-A single Item's local motion may follow progress through its Window. When separate internal actions
-answer separate lines, give them separate events or use a scene exposing those events. An outer
-semantic Window alone cannot keep every internal action aligned with changed speech.
-
-## Include sound deliberately
-
-Source audio is opt-in: `source-audio="content"` selects the direct source, or a child Layer id selects
-that Layer's sound. A `Sound` child can instead attach normalized audio to an Item's entrance/exit
-or to a Sequence handoff. The Track publishes `.visual`, `.program`, and `.audio` when sound is present.
-Film includes the desired outputs separately.
-
-Source audio follows the selected sampling policy; holding a picture does not synthesize held sound.
-An otherwise silent overlay leaves the Film's existing Sound contribution audible. Use
-[Audio Track](audio-presentation.md) for independent sound placement and avoid routing the same voice twice.
-
-When uninterrupted visual coverage matters, inspect semantic pause boundaries, source exhaustion
-and transition opacity together. [B-roll](../playbooks/craft/b-roll.md) owns the editorial choice;
-[review](review.md#make-the-composition-work) locates an unintended exposure in the actual picture.
diff --git a/skills/hypit/references/production/media.md b/skills/hypit/references/production/media.md
index 2338939f..4e275494 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](media-presentation.md)
+before using it in a component or a model reference. [Media presentation](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
@@ -21,14 +21,14 @@ Keep source facts, preparation and presentation distinct:
| A model reference | The exact image, video or audio input accepted by that model's Surface; normalization is not a universal prerequisite. |
Files, generated Outputs and earlier Results are sources of these values. A reference need not
-appear in the film. A video containing a person is not automatically a SemanticTake; the author
-establishes that relationship when it performs a Script passage. [Runs](runs.md) owns explicit Result
+appear in the film. A video containing a person is not automatically semantic; the author establishes
+that relation by aligning one Script Segment to its local domain. [Runs](runs.md) owns explicit Result
reuse. [Image operations](image-operations.md) owns still-image preparation.
-Normalization establishes moving media's frame clock, local duration and selected picture/audio
-streams. A SemanticTake adds one Script passage and its local word/boundary positions.
-[Timeline assembly](timeline.md) then places that Take in the work. Independent material goes to its
-own component without a SemanticTake. Its presentation still uses the same Timeline for event times.
+Normalization establishes moving media's frame clock, local domain and selected picture/audio
+streams. `NarrativeAlignment` separately adds one Script Segment's local word/boundary positions.
+[Timeline construction](timeline.md) may consume the prepared Extent. A domain projector may consume
+the local domain with an equal-length Timeline Window. Neither operation changes the media value.
## Files and generated Outputs
@@ -62,14 +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 and align that result as the SemanticTake below.
+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
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.
-An image reference can enter a model directly. A still placed by Media Track needs its actual
+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
with `space:Extent`; [spatial layout](spatial.md) explains extent versus destination Frame.
@@ -82,10 +82,9 @@ so their lengths and later playback can be combined precisely.
The following excerpt prepares a performance and an independent soundtrack:
```svml
-<import as="program" from="@hypit/program-space@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
-<program:Clock id="clock" frame-rate="30"/>
+<time:Clock id="clock" frame-rate="30"/>
<pipeline:Normalize id="performance-media" source={performance} clock={clock}
video="primary-moving" audio="default" span-authority="video"/>
<pipeline:Normalize id="music-media" source={music} clock={clock}
@@ -110,62 +109,45 @@ mix decisions in [Audio Track and sound mix](../playbooks/craft/sound-mix.md).
## Associate a performance with Script
-For a performance-led work, including pure A-roll and short drama, prefer this path even when the
-picture needs no additional graphics. Script preserves the performed wording and meaningful
-passages; semantic preparation lets later presentation and revisions use their actual times.
-
-For an already declared Script and prepared spoken performance:
+For performance-led work, Script preserves wording and meaningful events while alignment locates
+them on the accepted media's local domain:
```svml
<import as="whisperx" from="@hypit/whisperx@1"/>
-<whisperx:SemanticTake id="opening-semantic" narrative={story}
- segment={story.segment.opening} media={performance-media.media} language="en"/>
+<whisperx:Alignment id="opening-semantic" narrative={story}
+ segment={story.segment.opening} media={performance-media.media}
+ domain={performance-media.domain} language="en"/>
```
-Set `language` to this Take's explicit spoken language code, such as `ko` for Korean. The selected
-WhisperX service chooses its language-specific alignment model; ASR size and local resource
-preparation belong to the Runtime Profile. Follow [local tools](../environment/local-tools.md)
-when preparing a new language. The installed `packages/whisperx/README.md` owns the exact language
-expression and preparation examples.
-
-WhisperX supplies timed speech evidence; alignment locates the authored Script in that evidence.
-Script remains the wording authority, and this step establishes where its words occur in the
-performance. The result `opening-semantic.take` contains the same media and that Segment's local
-timing. [Timeline assembly](timeline.md) places Takes sequentially or at authored starts and
-translates their local positions into Program time.
-Use the performed language supported by the selected package and Endpoint.
-
-Audio-only A-roll follows the same path with audio-only media. Its final speech can be a supplied
-recording, or Voice Clone can produce it from the Segment's Script and the person's Voice Reference.
-Normalize that audio with
-`video="none"`, `audio="default"` and `span-authority="audio"`, then align it to the same Segment.
-The resulting SemanticTake publishes semantic time and sound through Timeline assembly without inventing
-a visual performance; the work's Media, Typography or MG Tracks supply the picture.
-
-## Empty Segments use their media boundaries
-
-An ordinary Script Segment such as `<empty></empty>` can carry a passage without words. Its prepared
-media gives it a duration, so the resulting SemanticTake has the Segment's start/end Anchors and no
-timed Tokens. It enters the same Timeline assembly as a spoken Take. An interval with no performance
-material can instead be left open by Timeline placement or extent, with graphics authored there directly.
+Set `language` to the performed language supported by the selected WhisperX Endpoint. WhisperX
+supplies timed evidence; deterministic alignment associates it with Script. The result
+`opening-semantic.alignment` is `NarrativeAlignment`: Segment and Token boundaries on the named local
+domain. It carries no media and no Timeline position.
-The semantic Surface maps an empty Segment directly to its prepared media domain:
+Combine the alignment, its complete local domain and the equal-length Window in one explicit
+semantic projection:
```svml
-<whisperx:SemanticTake id="pause" narrative={story}
- segment={story.segment.pause} media={pause-media.media}/>
+<time:Timeline id="program" clock={clock} end="opening.end">
+ <time:Window id="opening" from="start" for={performance-media.extent}/>
+</time:Timeline>
+<semantic:Projection id="story-time" narrative={story} timeline={program.timeline}>
+ <semantic:Map alignment={opening-semantic.alignment}
+ domain={performance-media.domain} window={program.opening}/>
+</semantic:Projection>
```
-This performs boundary materialization without a transcription request because the Segment has no
-Tokens. Action, music or visual rhythm can determine the media duration. The ordinary SemanticTake
-enters Timeline assembly alongside spoken Takes. This supplies Segment boundaries, not automatic
-within-shot action detection. An event such as a silent door opening needs its own observed timing
-if another component must respond to it. A simple material edit does not require inventing a Segment.
+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.
## Give a still a duration when that is its role
-A still B-roll Item already occupies an authored Window. To make one or several images into a
+A still B-roll Clip already occupies an authored Window. To make one or several images into a
time-bearing clip, use StillVideo:
```svml
@@ -186,7 +168,7 @@ is assigned by the downstream Source relationships just like any other video.
```svml
<media:Transform id="edited" source={performance-media.media}>
<media:Trim tail="0.25s"/>
- <media:Retime rate="1.05" pitch="preserve"/>
+ <media:Retime rate="1.05"/>
</media:Transform>
<media:ExtractAudio id="voice-reference" source={edited.video} audio="default"/>
<media:ExtractFrame id="frame-reference" source={edited.video}
@@ -194,7 +176,7 @@ is assigned by the downstream Source relationships just like any other video.
```
Transform applies its operations in order. These Outputs are BlobArtifacts; normalize an edited
-clip again when feeding it into a prepared-media input, and align the edited performance when its
+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.
`ExtractFrame` also accepts `first`, `frame:<index>` and `time:<seconds>`.
@@ -206,16 +188,14 @@ and `@hypit/background-removal`; select the operation that matches the asset's i
## 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 a different presentation Style.
-A transparent video can enter the same SemanticTake/Timeline/Performance path as an opaque video.
-A circular clip or rounded Frame instead masks a presentation geometrically; it does not remove
-the subject's background from the underlying bytes.
+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.
-If the whole performance should use a processed picture, prepare it before the SemanticTake and
-place that Take. When both the original and processed picture appear, keep both outputs and bind the
-one each presentation needs. For example, Timeline can hold the cutout while an opening Media Item
-explicitly uses the original. [Performance](performance.md#choose-the-picture-actually-held-by-the-timeline)
-explains that presentation boundary.
+When original and processed pictures both appear, retain both and bind 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.
For a moving portrait, the installed `@hypit/volcengine-matting` package exposes `Portrait` with
`source={performance.video}` and publishes `cutout.video`; query its vocabulary and README for
@@ -233,11 +213,8 @@ 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.
-A picture-only operation can preserve the accepted local timing when frames still represent the
-same source instants. A project preparation component may explicitly combine that picture with the
-accepted Take's audio and evidence. That is an authored computation with both inputs, not automatic
-variant inheritance. Trimming, retiming or replacing the performance changes the relationship and
-requires timing prepared for that result. [Reuse boundaries](authoring.md#reuse-produced-work-explicitly)
+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.
Choose source proportions and framing for the actual footage the work needs. A full-frame spoken
diff --git a/skills/hypit/references/production/performance.md b/skills/hypit/references/production/performance.md
deleted file mode 100644
index bab0ab68..00000000
--- a/skills/hypit/references/production/performance.md
+++ /dev/null
@@ -1,114 +0,0 @@
-# Presenting an existing performance
-
-Read this to present footage already placed on the [Timeline](timeline.md), including a pure A-roll
-work whose picture stays full-frame. Performance obtains that footage and its current source position;
-Uses direct how it appears. [Media Items](media-presentation.md) explicitly receive independent material
-and playback choices. Picture size, subject and transparency do not select between these paths.
-
-For a short drama, spoken scene or direct address, retain Script and the accepted SemanticTakes even
-when a single full-frame Style is the complete visual treatment. A-roll's semantic role continues
-through later reframing or coverage. An audio-only performance needs [Sound](sound.md) but supplies
-no picture for Performance.
-
-## Broad treatment, local Uses
-
-```svml
-<import as="performance" from="@hypit/performance@1"/>
-<performance:Style id="full" frame={layout.full} appearance={recipes.media.presenter}/>
-<performance:Style id="side" frame={layout.side} appearance={recipes.media.presenter}/>
-<performance:Track id="presenter" timeline={program.timeline} canvas={canvas}>
- <performance:Use style={full}/>
- <performance:Use during={story.selection.explanation} style={side}/>
-</performance:Track>
-```
-
-The excerpt assumes the Timeline, Canvas, Frames and Media appearance Recipe exist. The ordinary
-Style shares Media fitting, crop anchors, rounded clipping, border and sample appearance. Include
-`presenter.visual` and a [Sound](sound.md) presentation separately in Film. Sound obtains the same
-placed material and handles gain, silence and explicit source blending.
-
-An unqualified Use sets the broad treatment. Later matching Uses replace the whole choice locally;
-this is the same broad/local rule as Caption styling. Performance selects frame Windows; Caption
-selects authored display units. Separate presentation Tracks remain independent.
-
-Use supports `during`, `at` + `for`, `until` + `for`, and `start` + `end`. A Moment can start a
-fixed-duration change. No matching rule contributes no picture; an intentionally empty winning
-rule stays empty. Source gaps and audio-only Takes need no visual stand-in. Extend Timeline's end
-for a code-authored closing passage, and place its graphics there directly.
-
-## Preserve source playback and the original Use time
-
-Timeline placement determines which source frame is current. If a Take starts at program second 5,
-a Use beginning at second 7 sees source second 2. Hiding and showing footage does not restart it.
-The Style also retains the original Use Window for its animation, even where another Use covers
-part of it or a Take boundary cuts through it. Visibility, source playback and animation progress
-are separate facts.
-
-The ordinary Style draws available visual sources in Timeline declaration order, later above
-earlier. Timeline itself retains them all. An audio-only Take contributes no picture; a gap remains
-empty. Overlapping sources do not automatically crossfade, and separate Performance Tracks can
-intentionally show the same content in multiple places.
-
-For simultaneous views of the current performance, share this Timeline mapping and let each visual
-owner choose its crop and treatment. A close foreground and enlarged background can therefore show
-the same source instant. A replay starting from a chosen earlier moment has a different playback
-relationship: supply that prepared source to Media or the scene explicitly. Neither use requires
-another copy of the speech in Film.
-
-## Choose the picture actually held by the Timeline
-
-A Take contains the selected prepared picture, including any background removal already performed.
-Changing its Frame, crop or Style does not restore an original background. Keep the original output
-and bind it explicitly when a presentation needs it. [Media preparation](media.md#keep-original-and-processed-material-explicit)
-owns that material choice and any preparation adapter.
-
-For example, a cutout can continue in a lower corner through Performance while an opening Media Item
-shows the retained original from the start of the same passage. If the handoff occurs later inside
-a Take, both pictures need the corresponding source position. A project Style or scene can receive
-the original explicitly and use the Timeline projection to sample it, when the two inputs share
-that frame mapping. It does not search for hidden variants or assume two independent clips align.
-Route the intended voice once through Sound. A direct cut between those materials needs no animated
-journey between their Frames. If the intended effect instead dissolves an original into its cutout,
-both views must depict the corresponding source instant and align the subject through their fitting,
-crop and transforms. Equal destination Frames alone do not establish equal subject geometry.
-
-## Give a new visual behavior a Style
-
-A recurring presenter motion can be a project Style. It receives the Timeline, Canvas and original
-Use Window, plus its own explicit parameters. Think of a specific reusable behavior, such as a
-full-frame viewport moving into a side Frame. The family owns its trajectory and exposes the inputs
-that make it useful; arbitrary Styles do not automatically morph into one another.
-
-For a direct switch, a local Use selects the new treatment at its semantic event. For a continuous
-handoff, declare the initial treatment, then the settled treatment starting at the event, then the
-short movement Use last. It covers the start of the settled treatment and reveals that treatment
-when finished. Match both endpoint Frames and their source fitting/crop through shared values so the
-subject meets the intended view. The source video continues playing throughout; partial coverage
-does not reset its animation clock. Additional actions that answer other words receive their own
-projected events, as described in
-[component design](component-design.md#let-meaning-drive-the-behavior).
-
-An overlap transition is also a Use. For two Takes, its Window can run from the next Segment's start
-to the previous Segment's end:
-
-```svml
-<performance:Use style={mix}
- start-source={story.segment.next} start="segment.start"
- end-source={story.segment.previous} end="segment.end"/>
-```
-
-Define `mix` in the chosen family with explicit outgoing/incoming sources. Those roles are separate
-from the occurrence Window. The ordinary Style layers simultaneous footage in declaration order;
-an overlap by itself does not create a transition.
-
-For implementation, a Style uses `performanceStyle(fragment, bindings)` from
-`@hypit/hypit/performance`. The fragment receives `timeline`, `canvas`, `window` and family-owned typed
-inputs, and exports `visual: VisualTrack`. Bind extra inputs to resolved author references; they
-become explicit graph dependencies at each Use. Use `projectTimelineMedia` for source identities,
-program spans and source offsets, and the shared temporal helpers for additional events. All existing
-structural/browser drawing capabilities remain available. [Track authoring](track-authoring.md) and
-[component drawing](component-visuals.md) explain that implementation path.
-
-When presenter and graphics share a larger coordinated scene, give that scene its own component.
-Choose the abstraction by the behavior worth reusing; a project Style does not have to become an
-official preset before it can be used.
diff --git a/skills/hypit/references/production/rendering.md b/skills/hypit/references/production/rendering.md
index ab9394bc..effcd0c7 100644
--- a/skills/hypit/references/production/rendering.md
+++ b/skills/hypit/references/production/rendering.md
@@ -16,39 +16,35 @@ With the named inputs already declared:
<import as="film" from="@hypit/film@1"/>
<import as="render" from="@hypit/render-hyperframes@1"/>
-<import as="sound" from="@hypit/sound@1"/>
-<sound:Style id="voice-style"/>
-<sound:Track id="voice" timeline={speech.timeline}>
- <sound:Use style={voice-style}/>
-</sound:Track>
-
-<film:Film id="main" canvas={canvas} timeline={speech.timeline}
+<film:Film id="main" canvas={canvas.canvas} timeline={speech.timeline}
appearance={look.film.main}>
- <film:Track source={performance.visual}/>
- <film:Track source={voice.audio}/>
+ <film:Track source={picture.visual}/>
+ <film:Track source={mix.audio}/>
<film:Track source={coverage.visual}/>
- <film:Track source={captions.track}/>
+ <film:Track source={captions.visual}/>
<film:Track source={music.audio}/>
</film:Film>
<render:Video id="final" composition={main.composition} timeline={speech.timeline}/>
```
An example Film Recipe is `film.main { background: #18212A; }`. Canvas supplies the picture dimensions;
-the Timeline supplies program time. Include each wanted audio output explicitly. A covering
-picture leaves the included performance audio audible. Layer order is authored in the Tracks'
-Presents, so moving these Film children does not reorder the picture.
+the Timeline supplies program time. `picture.visual` is a Visual Track output and `mix.audio` is an
+Audio Track output. Include every wanted output explicitly: placing the same normalized media in a
+Visual Clip and an Audio Clip is what makes both its picture and its audio present.
+Layer order is authored in the Visual Tracks' Presents, so moving these Film children does not
+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
-need only the Performance and Sound contributions, with Caption when wanted. Additional coverage
+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
-context in which Tracks resolve Script references. For a pure MG piece, use the same Timeline with
-an explicit end and zero Takes, and pass it to the components, Film and Render:
+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:
```svml
<import as="time" from="@hypit/timeline-author@1"/>
@@ -56,13 +52,13 @@ an explicit end and zero Takes, and pass it to the components, Film and Render:
<time:Timeline id="animation" clock={animation-clock} end="8s"/>
<!-- conversation is the project's own visual component. -->
-<chat:Scene id="conversation" timeline={animation.timeline} canvas={canvas} font={font}
- during="program" title="Launch crew">
+<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."/>
</chat:Scene>
-<film:Film id="main" canvas={canvas} timeline={animation.timeline} appearance={look.film.main}>
- <film:Track source={conversation.track}/>
+<film:Film id="main" canvas={canvas.canvas} timeline={animation.timeline} appearance={look.film.main}>
+ <film:Track source={conversation.visual}/>
</film:Film>
<render:Video id="final" composition={main.composition} timeline={animation.timeline}/>
```
@@ -73,8 +69,8 @@ separate duration-free input for normalizing real media. Drawing code produces t
requested frame; the Film's background supplies the canvas color. With no AudioTrack, the delivered
video is silent. Render ranges and worker settings apply in the same way as for spoken work.
-Media, Typography, Audio and the graphic Tracks accept this same Timeline. Performance obtains
-any available prepared footage from it. Caption
+Media, Typography, Audio and the graphic Tracks accept this same Timeline. Visual and Audio Clips
+receive ordinary media and Windows explicitly; the Timeline does not contain or discover media. Caption
uses its speech-linked document; authored chat text belongs to the chat scene. The working example
`examples/semantic-composition/chat.svml` and its `@example/chat-scene` package show the complete
code-only composition, including scrolling and arbitrary message arrivals.
@@ -97,7 +93,7 @@ For this example, the renderer evaluates the original page at seconds 8–12 and
as a four-second clip starting at zero. An animation already in progress at second 8 keeps that state.
**The range limits final rendering. Upstream generation still follows the selected graph.** Keep
-the Run Candidates for usable media and SemanticTakes when inspecting a Caption or MG revision.
+the Run Candidates for usable normalized media and alignment evidence when inspecting a Caption or MG revision.
Inspect `hypit plan` for the work that remains before submission. [Authoring](authoring.md#reuse-produced-work-explicitly)
explains choosing the reuse boundary.
diff --git a/skills/hypit/references/production/review.md b/skills/hypit/references/production/review.md
index a09ca498..17137fb6 100644
--- a/skills/hypit/references/production/review.md
+++ b/skills/hypit/references/production/review.md
@@ -60,9 +60,9 @@ the agreed commission. [Service selection](../environment/model-and-provider.md#
Read missing behavior through its material and presentation together. For intended speech, listen to
the selected Film: an available audio file establishes material, while admission and the chosen
-Sound or Audio contribution establish whether that material reaches the Film. For intended physical
+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](sound.md) and [Film assembly](rendering.md)
+[media admission](media.md), [sound presentation](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
diff --git a/skills/hypit/references/production/runs.md b/skills/hypit/references/production/runs.md
index d0ff7aa9..a9a22649 100644
--- a/skills/hypit/references/production/runs.md
+++ b/skills/hypit/references/production/runs.md
@@ -7,8 +7,9 @@ A Run says what this execution should complete and which existing or alternative
use. A **Target** names a deliverable Output. A **Candidate** supplies an Output needed along the
way. The selected dependencies determine the work that remains.
-For example, changing a title can keep the performance and its timing while producing a new final
-video. The Source describes the changed title; the Run keeps the produced Take.
+For example, changing a title can keep the produced performance media, its local temporal domain and
+its alignment evidence while producing a new final video. The Source describes the changed title;
+the Run keeps those independent completed Outputs.
One Run uses these author-facing declarations:
@@ -34,15 +35,20 @@ not Run declarations.
<svrun version="1">
<author source="./production.svml"/>
<target output="final.video"/>
- <build-record id="kept-take" build="bld_..." output="opening-semantic.take"/>
- <satisfy output="opening-semantic.take" candidate="kept-take"/>
+ <build-record id="kept-media" build="bld_..." output="opening-normalized.media"/>
+ <build-record id="kept-domain" build="bld_..." output="opening-normalized.domain"/>
+ <build-record id="kept-alignment" build="bld_..." output="opening-alignment.alignment"/>
+ <satisfy output="opening-normalized.media" candidate="kept-media"/>
+ <satisfy output="opening-normalized.domain" candidate="kept-domain"/>
+ <satisfy output="opening-alignment.alignment" candidate="kept-alignment"/>
</svrun>
```
Replace `bld_...` with the actual Build id found through Results. The historical `output` is the
-name in that Result; the `satisfy output` is the current Author Output. Keeping this SemanticTake
-preserves both media and timing when its Script identities still fit. A changed Caption or MG can
-then recompute downstream. Marker and display-only edits may also preserve the Take; use 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
+preserve the alignment; use the
[reuse table](authoring.md#reuse-produced-work-explicitly) to distinguish them from changed speech or media.
Each Run has one Author entry. Its Targets name public computed Outputs, such as `main.composition`
@@ -60,9 +66,9 @@ A file can replace a byte-producing Output:
```
Here the file replaces the generated video bytes. Normalization and alignment still follow it.
-Selecting a completed SemanticTake instead preserves its media, Script association and timing
-together. Choose the Output whose meaning matches what should stay; the receiving Type identifies
-which kind of value fits that position.
+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
+matches what should stay; the receiving Type identifies which kind of value fits each position.
## Use a Fragment when a Candidate needs computation
@@ -96,7 +102,7 @@ The resulting Candidate is named `product-hold.video`. Selecting it replaces the
## Generate material while composing
Media requests depend on the Script, direction, references and requested duration. Once those
-choices are ready and the commission covers their cost, a Run can target the prepared Takes while
+choices are ready and the commission covers their cost, a Run can target the prepared material while
component and Recipe work continues. Shared decisions such as where a presenter leaves room for
an overlay belong in Treatment. Translate the material side into visible camera facts for image
and video direction; pass the composition side as actual layout and event inputs. Independent
@@ -107,15 +113,16 @@ The small [production Source](examples/production.svml), [Recipe](examples/look.
these execution choices. Copy them together into a project. The simple performance request shows
system wiring; the work's actual casting, references and direction come from its Treatment and Craft.
-`material.svrun` targets `opening-semantic.take`. While it runs, the author can work on the title and
-its placement. Once the Take completes, select it with `build-record` in the production Run so that
-rendering uses the produced performance and its word timing. If material is already available, use
-it directly. Choose Targets according to the dependencies the current work needs.
+`material.svrun` targets the opening alignment, which also demands normalization and the local domain.
+While it runs, the author can work on the title and its placement. Once those Outputs complete, select
+the media, domain and alignment with `build-record` in the production Run so rendering uses the produced
+performance and its word timing. If material is already available, use it directly. Choose Targets
+according to the dependencies the current work needs.
For a focused composition change, [detail.svrun](examples/detail.svrun) targets frames 30–90 from the
-same Source and reuses that Take. Replace its example Build id with the actual Result id. The new
+same Source and reuses those prepared Outputs. Replace its example Build id with the actual Result id. The new
Build evaluates the changed composition and selected render interval. The final Run can reuse the
-same Take for full delivery.
+same material and evidence for full delivery.
[Rendering](rendering.md#choose-a-render-interval-in-frames) explains frame ranges and reuse;
[Review](review.md) explains judging the actual arrangement. [Studio](studio.md) provides an
diff --git a/skills/hypit/references/production/script-syntax.md b/skills/hypit/references/production/script-syntax.md
index 8d14a30c..ad0ac09a 100644
--- a/skills/hypit/references/production/script-syntax.md
+++ b/skills/hypit/references/production/script-syntax.md
@@ -146,7 +146,7 @@ One Script publishes the full Narrative and the narrow views needed by the rest
| Reference | What it carries |
| --- | --- |
| `{story}` | The complete authored Narrative. |
-| `{story.segment.hook}` | The `hook` Segment as a NarrativeExcerpt for one SemanticTake. |
+| `{story.segment.hook}` | The `hook` Segment as a NarrativeExcerpt for generation, alignment or another semantic consumer. |
| `{story.segment.hook.dialogue}` | Role-aware dialogue using the spoken side of Dual Text, suitable for a speaking performance request. |
| `{story.segment.hook.speech}` | Pronunciation-only Text, suitable for `hypit measure` or independent speech. |
| `{story.caption}` | Display Words, Alignment Units, attributes, Roles, and authored Cue Breaks for Caption. |
diff --git a/skills/hypit/references/production/sound.md b/skills/hypit/references/production/sound.md
deleted file mode 100644
index 979f287e..00000000
--- a/skills/hypit/references/production/sound.md
+++ /dev/null
@@ -1,75 +0,0 @@
-# Presenting existing sound
-
-Use Sound to present audio from Takes already placed on the [Timeline](timeline.md). Use
-[Audio Track](audio-presentation.md) for independently supplied sound. Sound chooses how existing sources are heard; [Performance](performance.md)
-chooses how their pictures appear. Neither changes the Script or the Take placements.
-
-## Broad treatment and local Uses
-
-```svml
-<import as="sound" from="@hypit/sound@1"/>
-<sound:Style id="normal"/>
-<sound:Style id="opening" gain="0" end-gain="1"/>
-<sound:Style id="silent" gain="0"/>
-<sound:Track id="voice" timeline={program.timeline}>
- <sound:Use style={normal}/>
- <sound:Use at="0f" for="2s" style={opening}/>
- <sound:Use during={story.selection.demonstration} style={silent}/>
-</sound:Track>
-```
-
-Select `voice.audio` in Film to hear this presentation. Timeline retains source material; Sound
-chooses how it is heard. Independent music and effects remain separate Film contributions.
-
-The first Use sets a broad treatment. The last matching Use replaces it locally, including when
-the winner is silent. A later normal Use can restore sound inside a muted passage. No matching
-Use means no sound from this Track. This is the same broad/local presentation rule as Performance
-and Caption, with time Windows as Sound's domain.
-
-The ordinary Style chooses the last Timeline-declared active source with audio. A Take without an
-audio member contributes no candidate. No Take means no original sound; it does not affect separate
-music or effects. A recording that contains silence is still an audio source.
-
-`gain` is a linear amplitude multiplier, normally 1; `end-gain` defaults to the same value. Different
-values create a linear change over the Use's full Window. Use `gain="0"` for silence, or
-`gain="1" end-gain="0"` for a fade-out. A leading Timeline gap has no source to fade: attach an
-opening fade to the first Take's actual start when it begins later than the program.
-
-All shared time forms apply: `during`, `at` + `for`, `until` + `for`, and `start` + `end`. Word-related
-changes can follow Selections or Moments; independently timed changes can use seconds or frames.
-The Window governs treatment progress, while the Take placement governs source playback. After a
-local override, both resume at the progress appropriate to the current time.
-
-## Explicit source relationships
-
-For a crossfade, a project Style selects its outgoing and incoming Segments explicitly. An ordinary
-Use then selects the overlap Window. A Style declaration might look like:
-
-```svml
-<mix:Crossfade id="handoff"
- outgoing={story.segment.first} incoming={story.segment.second}/>
-<sound:Track id="voice" timeline={program.timeline}>
- <sound:Use style={normal}/>
- <sound:Use style={handoff}
- start-source={story.segment.second} start="segment.start"
- end-source={story.segment.first} end="segment.end"/>
-</sound:Track>
-```
-
-Here `mix:Crossfade` is a project-defined Style, not a built-in Sound tag. Its complete example ships
-at `examples/semantic-composition/packages/sound-styles/` in the Hypit Distribution. The interval
-locates the effect; the bound sources determine its roles. Sound does not infer a mix from a visual
-transition. A family for intentional simultaneous speech can retain both sources at full gain.
-
-## Author a new sound Style
-
-Use `soundStyle(fragment, bindings)` from `@hypit/hypit/sound`. Its fragment receives `timeline` and
-the original `window`, plus the family's typed bindings, and exports `audio: AudioTrack`. A Surface
-publishes this definition as an inline `soundTypes.style` value. Each Use expands normal graph edges.
-
-`sourceSound(timeline, window, segment, { gain, endGain })` selects one existing source, and
-`ordinarySound(timeline, window, { gain, endGain })` provides the usual last-source behavior. Known
-sources without audio return no clips. A custom family can combine explicit sources or author a
-richer gain envelope using ordinary AudioClip data. No new renderer mode is needed.
-See [component authoring](track-authoring.md) for packaging and [sound direction](../playbooks/craft/sound-mix.md)
-for deciding what the audible change contributes to the work.
diff --git a/skills/hypit/references/production/source-syntax.md b/skills/hypit/references/production/source-syntax.md
index e4f475ef..058a2d0f 100644
--- a/skills/hypit/references/production/source-syntax.md
+++ b/skills/hypit/references/production/source-syntax.md
@@ -56,7 +56,12 @@ Output paths are package vocabulary, not inferred from the element's tag:
- an imported `media:Image id="logo"` publishes `{logo}`;
- `gpt:Image id="portrait"` publishes `{portrait.image}`;
- `pipeline:Normalize id="prepared"` publishes `{prepared.media}`;
-- `time:Timeline id="speech"` publishes `{speech.timeline}`. Performance and Sound separately publish the picture and sound contributions selected in Film.
+- `time:Timeline id="speech"` publishes `{speech.timeline}`;
+- `typo:Flow id="title"` publishes `{title.occurrence}` and `{title.visual}`;
+- `visual:Track id="picture"` publishes `{picture.visual}` and `{picture.program}`;
+- `audio:Track id="mix"` publishes `{mix.audio}`.
+
+Visual and Audio Tracks separately publish the picture and sound contributions selected in Film.
Inspect `hypit vocabulary` for the actual Surface's exports and use the published path it reports.
Public bindings can be authored Records or realizable Logical Outputs. Script,
@@ -153,8 +158,9 @@ are not executed.
To reuse a prior Output, declare a `build-record` Candidate and select it with `satisfy`; the prior
Result name and the current Logical Output name can differ. A raw MP4 file is a Blob Artifact, not
-an aligned SemanticTake. Select Candidates by their real nominal Type and creative meaning, retaining
-normalization or alignment where still needed. [Runs](runs.md) explains complete Candidate forms,
+normalized media or alignment evidence. Select Candidates by their real nominal Type and creative
+meaning, retaining normalization, local temporal-domain recovery or alignment where still needed.
+[Runs](runs.md) explains complete Candidate forms,
Fragment inputs and exports; [Authoring](authoring.md) owns the creative reuse decisions;
the installed Fragment package owns its own input and export names.
diff --git a/skills/hypit/references/production/spatial.md b/skills/hypit/references/production/spatial.md
index 0a5bb0fd..9ddb97e6 100644
--- a/skills/hypit/references/production/spatial.md
+++ b/skills/hypit/references/production/spatial.md
@@ -4,11 +4,12 @@ Read this when positioning or fitting media, text or a project component. Timing
[Timing](timing.md); it is independent of these coordinates. Read
[component design](component-design.md) when deciding which content shares layout or motion;
[image direction](../playbooks/craft/image-direction.md) owns the source camera view. This page owns
-the destination geometry, for Performance, independent Media and project scenes alike.
+the destination geometry for Visual Clips and project scenes alike.
## Canvas, extent and destination
-The Canvas gives the final image's pixel dimensions and coordinate basis. Introduce Frames and
+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.
@@ -24,9 +25,7 @@ presentation choices. Translate required source framing into visible camera fact
<space:Canvas id="canvas" width="1080" height="1920"/>
<space:Extent id="photo-size" width="1600" height="1200"/>
-<space:Frame id="full" within={canvas}
- left="0%" top="0%" right="100%" bottom="100%"/>
-<space:Frame id="content" within={full}
+<space:Frame id="content" within={canvas.bounds}
left="6%" top="8%" right="94%" bottom="90%"/>
```
@@ -52,40 +51,59 @@ parent when that is the intended composition.
For text, `space:Point` supplies a pixel position and `space:Path` supplies authored Move/Line/curve
commands. [Fonts and text](fonts-and-text.md) shows which Typography placement consumes each.
-## Fit the source into the Frame
+## Map a source plane and treat its Frame
-Media Track and the ordinary Performance Style share two spatial roles:
+Visual Clips keep three different spatial facts separate:
-- The **destination Frame** places the visual on the Canvas and supplies its outer shape.
-- The **fitted content rectangle** places the scaled source inside that Frame. Its size and position
- come from the source's real Extent and the appearance Recipe's fit and alignment choices.
+- The source's **IntrinsicExtent** bounds its own local pixel plane.
+- 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.
-Supply the destination Frame and the source's actual dimensions. A still image needs an Extent;
-prepared moving media already carries its dimensions. The component calculates the content rectangle.
-Border and padding reduce the area used for fitting inside the outer Frame. This inset is derived
-from those settings, rather than requiring another authored Frame.
+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
+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.
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.
-Choose fitting through the component's appearance Recipe:
+Choose ordinary fitting directly on the Clip:
- **contain** keeps the complete image visible and may leave space around it;
- **cover** fills the destination and may crop the image;
- **stretch** changes the source proportions to occupy the destination.
-The selected Media/Performance vocabulary also exposes `fit-width`, `fit-height`, `native` and `scale-down` when one
+The Visual Track vocabulary also exposes `fit-width`, `fit-height`, `native` and `scale-down` when one
dimension or the source's own pixel size should determine the scale. The default is centered
-`contain`. `fit: stretch` is spatial resizing; Media Track's `playback: stretch` is a separate choice
-about video speed.
+`contain`. `fit: stretch` changes only spatial sizing. Timed-source sampling is the independent
+partial relation documented in [Visual Clips](visual-clips.md); it is never inferred from spatial fit.
+
+When fit vocabulary is too narrow, author the mapping itself and pass it with `mapping`. This is the
+open spatial escape hatch; it can rotate, skew, reflect or place a source outside its Clip Frame.
+The matrix maps source-local pixels directly into program-picture pixels:
+
+```svml
+<space:Map id="turned" xx="0" xy="-0.5" yx="0.5" yy="0" tx="920" ty="180"/>
+
+<visual:Track id="graphic" timeline={program.timeline}>
+ <visual:Clip image={poster} extent={poster-size} during={program.title}
+ frame={layout.full} z="20" mapping={turned}/>
+</visual:Track>
+```
+
+The equations are `x' = xx*x + xy*y + tx` and `y' = yx*x + yy*y + ty`. An explicit mapping is
+already in program coordinates, so it is mutually exclusive with the fit and alignment attributes.
+The Frame still owns clipping, border, padding, shadow and whole-Clip motion; it does not rewrite the
+mapping. Project components may construct the same `SpatialMap2D` through the public package API.
## Align the picture inside its destination
-The fit aligns a point on the scaled picture with a point in the fitting area:
+The fit shorthand aligns a point on the scaled source with a point in the fitting area:
-| Control in the appearance Recipe | Meaning |
+| Direct Clip control | Meaning |
| --- | --- |
| `frame-x`, `frame-y` | The destination alignment point, from `0` to `1` across the fitting area's width and height |
| `content-x`, `content-y` | The point on the scaled source that meets it, also from `0` to `1` |
@@ -103,30 +121,28 @@ the actual subject and composition; these coordinates express your crop choice.
## Shape the outer frame
-Clipping, border, padding, shadow and frame paint belong to the outer Frame. The shared appearance
+Clipping, border, padding, shadow and frame paint belong to the outer Frame. The optional treatment
Recipe uses `clip: frame` for a rectangular clip, `clip: rounded` with a pixel `radius` for rounded
corners, or `clip: none` to show overflow. A radius takes effect with the rounded clip.
-Here is a circular presenter inset; the named Canvas, SemanticTake and imported namespaces are
+Here is a circular presenter inset; the normalized media, local domain and imported namespaces are
already available:
```svml
-<space:AnchoredFrame id="presenter-frame" within={canvas}
+<space:AnchoredFrame id="presenter-frame" within={canvas.bounds}
x="94%" y="94%" width="320px" height="320px" anchor="bottom-right"/>
<time:Clock id="clock" frame-rate="30"/>
-<time:Timeline id="speech" clock={clock}>
- <time:Take source={opening.take}/>
+<time:Timeline id="speech" clock={clock} end="opening.end">
+ <time:Window id="opening" from="start" for={opening-media.extent}/>
</time:Timeline>
-<performance:Style id="presenter-style" frame={presenter-frame} appearance={look.presenter}/>
- <performance:Track id="presenter" timeline={speech.timeline} canvas={canvas}>
- <performance:Use style={presenter-style} during="program"/>
- </performance:Track>
+<visual:Track id="presenter" timeline={speech.timeline}>
+ <visual:Clip id="opening" media={opening-media.media} during={speech.opening}
+ frame={presenter-frame} z="20" fit="cover" treatment={look.presenter}/>
+</visual:Track>
```
```svs
look.presenter {
- stack-order: 20;
- fit: cover;
clip: rounded;
radius: 160;
border-width: 3;
@@ -149,40 +165,39 @@ the frame's paint and decoration have their own appearance.
## Move the frame or move its contents
-A lifecycle `motion` Recipe moves or fades the complete framed presentation, including its border
-and paint. `Sampling` children pan, zoom or rotate the fitted picture under that frame. Use Sampling
+A typed `Motion` moves or fades the complete framed presentation, 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:
```svml
-<media:Item media={prepared.media} during={story.selection.detail}
- frame={detail-frame} appearance={look.detail}>
- <media:Sampling at="start" zoom="1"/>
- <media:Sampling at="end" zoom="1.08" y="-18"/>
-</media:Item>
+<visual:Clip media={prepared.media} during={story-time.detail}
+ frame={detail-frame} z="20" fit="cover" treatment={look.detail}>
+ <visual:Sampling at="start" zoom="1"/>
+ <visual:Sampling at="end" zoom="1.08" y="-18"/>
+</visual:Clip>
```
-This excerpt belongs inside Media Track, with prepared media, a Selection, Frame and Recipe already
-available. Sampling fields apply to a direct-source Item or Member, or a sampled Layer.
+This excerpt belongs inside a Visual Track, with prepared media, a resolved Window, Frame and Recipe already
+available. Sampling fields apply to the Clip's sampled source.
`x` and `y` are pixel offsets, `rotate` is in
degrees, and `at` follows the source unit's active span from `start` to `end`, with percentages for
-intermediate keys. Sampling acts after the static fit; its movement can expose space inside the
+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.
-[Performance](performance.md) applies fixed or custom Styles to existing Timeline footage. A moving
-Style retains the original Use Window across partial coverage and Take boundaries. A scene that
+[Visual Track](visual-clips.md) places explicit footage through Clips. 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-browser-program), retaining
-source playback positions.
+[component program](component-visuals.md#compose-video-and-graphics-in-one-browser-program).
-[Media presentation](media-presentation.md) and [Performance](performance.md) own their content and
-playback inputs. Read their installed vocabulary for the complete appearance and motion fields.
+[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 the same geometry
+## Carry measured regions through an explicit peer track
-RegionTimeline contains already measured boxes indexed by program frame. Its recipe uses normalized
-`[x, y, width, height]` boxes and `null` for absent measurements, converted against the chosen Canvas.
-Take-local measurements need their actual program offsets. Reframed or cropped footage needs the
-corresponding spatial transform before its boxes can position text correctly.
+Region Track 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
+position text correctly.
[Caption tracking](../playbooks/craft/caption-tracking.md) explains producing and applying head
regions. In a new component's visual element tree, child positions are relative to their parent;
diff --git a/skills/hypit/references/production/studio-companions.md b/skills/hypit/references/production/studio-companions.md
index 71c05fcc..46919c13 100644
--- a/skills/hypit/references/production/studio-companions.md
+++ b/skills/hypit/references/production/studio-companions.md
@@ -15,12 +15,12 @@ facts can fully serve a one-off scene; useful Caption controls can coexist with
## Choose useful entities and lanes
Match the component's actual Module ABI, Surface and terminal output Type. Generic VisualTrack or
-AudioTrack entities are enough for simple occupancy. Use `project(context)` when the author needs
+AudioTrack entities are enough for ordinary Clip occurrences. Use `project(context)` when the author needs
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
-Caption Track can therefore render correct subtitles yet appear as a generic blue visual lane with
+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.
The package declares its role; Studio does not infer one from a tag name or the text in a picture.
@@ -44,7 +44,7 @@ published output. `requiredReferencedValue` reads an exact typed author referenc
| `stackOrder` | Order overlapping editor entities; this is separate from changing the Film's paint order. |
| Companion `attachments` and entity `lane` | Expose a meaningful child lane, such as reveals under a board, with its own fields. |
-Each declared lane is one row. Overlapping items remain selectable; selection raises the selected
+Each declared lane is one row. Overlapping entities remain selectable; selection raises the selected
rectangle within that row. Parent and attached lanes use the same behavior. Add a child lane when
it explains another authoring relationship, such as activation within a persistent board.
@@ -55,7 +55,7 @@ this with the board and its independent reveals.
## Put related rules in a Band
A Track's `bands` are internal strips sharing its label. For example, Caption shows Cue content
-with a bottom band for Style Uses; Performance and Sound show placed Takes with their Uses below.
+with a bottom band for Style Uses. Plain Visual and Audio Clips need no second authoring band.
The rule is a selectable entity with its own Window, even when overridden or currently empty.
It remains one Use across gaps and content boundaries.
@@ -140,8 +140,8 @@ facts and controls share Where, When and How; unpaged fields remain visible besi
Related scalar attributes can share one `record` draft through a binding's `attributes` list and
schema. Use object alternatives with a literal mode field when each choice needs different inputs;
-Once its required fields are complete, editing writes the chosen group together and removes unused members. Audio playback demonstrates
-this for its mode and stretch bounds. The package owns those alternatives; see
+once its required fields are complete, editing writes the chosen group together and removes unused
+members. The package owns those alternatives; see
the installed Studio adapter README, “Edit related attributes together,” for the exact declaration.
Select options may be plain strings or `{ value, label, description, preview }` entries. Color and
@@ -177,8 +177,8 @@ or activation. Ordinary Source and Recipe edits recompile within the current ses
Use the installed `packages/studio-adapter/README.md` for the complete minimal Companion and
activation example, `packages/studio/INSPECTOR.md` for field declarations, and
`packages/temporal-markup/EDITING.md` for exact time-form behavior. These are package references
-inside the installed Distribution. Ranking, Caption Fine and Media Track Companions demonstrate
-persistent events, Cue content with Style Uses, and material occupancy respectively.
+inside the installed Distribution. Ranking, Caption Fine and Visual Track Companions demonstrate
+persistent events, Cue content with Style Uses, and ordinary visual Clip occurrences respectively.
Try the component in its actual Run: select a meaningful picture part, inspect the corresponding
timeline entity, change an exposed value and inspect the owning Source and resulting picture.
diff --git a/skills/hypit/references/production/studio.md b/skills/hypit/references/production/studio.md
index 61a403a1..643a9f43 100644
--- a/skills/hypit/references/production/studio.md
+++ b/skills/hypit/references/production/studio.md
@@ -145,7 +145,7 @@ Comments is a review view of the editable work; the exported file is the deliver
Alongside the delivered video, a brief look at its editable production can make the handoff more
tangible. When Studio is readily accessible to the user, open the finished work and share the session
-URL. Use a Run that reuses the completed media and SemanticTakes while keeping its Tracks and Recipes
+URL. Use a Run that reuses the completed normalized media, local domains and alignment evidence while keeping its Tracks and Recipes
available for editing. Reuse a suitable existing session or launch one as described above.
Point out something specific to this piece: a reveal tied to a word, the Caption styling, or a
@@ -163,7 +163,7 @@ include when the user wants to continue editing on another machine.
| Timeline | Semantic Segments, Selections and Moments, plus the component-projected Track entities and their visible intervals, materials or event lanes. A rectangle may describe occupancy, activation or persistent visibility; read the component's meaning. |
| Inspector | With nothing selected, project, Canvas, time and Run facts. For a selected entity, its declared read-only facts and adjustable fields, organized under Where, When and How where applicable. |
| Tasks | One card per Build, grouped into ongoing and finished. Active status and progress come from the selected Runtime; completed, failed and cancelled Builds come from project Results. Cards retain the source Run, times and any failure or attention reason. |
-| Artifacts | Image, video and audio file Outputs from project Results, including those already published by ongoing Builds. Use the sidebar to choose all media, videos, images or audio. View media on a Build opens its Outputs; opening the Artifacts tab returns to project media. Composite Outputs such as normalized media and Semantic Takes stay intact and do not add their internal files to this gallery. Click a card to view it in the central preview; video and audio have playback and a time slider. Back to composition returns to the existing composition position. Previewing a file does not select it as a Candidate in the Run. |
+| Artifacts | Image, video and audio file Outputs from project Results, including those already published by ongoing Builds. Use the sidebar to choose all media, videos, images or audio. View media on a Build opens its Outputs; opening the Artifacts tab returns to project media. Structured Outputs such as normalized media and NarrativeAlignment stay intact and do not add their internal files to this gallery. Click a card to view it in the central preview; video and audio have playback and a time slider. Back to composition returns to the existing composition position. Previewing a file does not select it as a Candidate in the Run. |
A declared lane stays one row even when items overlap. Later items cover earlier ones at equal
stacking order; selecting an item brings its full rectangle forward within that lane. This changes
@@ -218,16 +218,18 @@ through the selected Style. It edits the shared font declaration; its weight and
available in the chosen family. A local font continues to use its exact file. A project component
can offer its own font or preset choices through Companion fields.
-Timeline's placed Takes and complete extent provide reference information. Edit their `at` and
-`end` declarations in Source when their placement should change. Presentation handles edit Uses
-or component events; they do not move Takes or adjust Canvas dimensions implicitly.
+Timeline's declared Instants, Windows and complete extent provide reference information. Edit their
+`at`, `from`, `until`, `for` and `end` declarations in Source when temporal construction should change.
+Edit the Timeline declaration or domain projection declaration that owns a temporal relationship.
+Clip editing handles its source occurrence; a component Companion handles its own Sources, Uses or
+events. Neither rewrites semantic projection or adjusts Canvas dimensions implicitly.
Timing edits follow the authored relationship. A direct Selection or Moment edits that identity
in Script; a quoted expression edits its local clock value or offset; a duration changes independently.
[Timing and edit behavior](timing.md#choose-what-a-later-edit-changes) gives the complete forms,
affinity choices and shared-consumer consequences. Marker moves preserve unrelated prose whitespace. With unchanged spoken tokens and identities,
-new marker references can use the existing Take's anchor times. [Reuse boundaries](authoring.md#reuse-produced-work-explicitly)
-explain when to retain prepared Takes and when to retain only their upstream media.
+new marker references can use the existing alignment evidence. [Reuse boundaries](authoring.md#reuse-produced-work-explicitly)
+explain when to retain media, its local domain, alignment evidence or only an upstream generated file.
A successful parameter or timeline edit saves the owning Source and recompiles the selected Run
for the view. Rejected edits retain the accepted Source and values. Result renaming instead updates
diff --git a/skills/hypit/references/production/system.md b/skills/hypit/references/production/system.md
index 071707b3..7002b13b 100644
--- a/skills/hypit/references/production/system.md
+++ b/skills/hypit/references/production/system.md
@@ -3,167 +3,120 @@
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.
-> Give semantics to the timeline, rather than the timeline to semantics.
->
-> Give layers to the canvas, rather than the canvas to layers.
-
-The work has a complete time range and a canvas. Attach events to their meaning in the performed
-work; introduce component boundaries where content shares useful layout, state or motion. Semantic
-coverage need not fill time, and visual components need not partition the canvas into fixed regions.
-The author decides which relationships the work needs. Hypit expresses and realizes them.
-
-## Materials acquire their roles through use
-
-A supplied file, a generated Output and a reused Result can supply the same kind of material.
-An image has dimensions; moving media has local time and selected picture/audio streams. Transparency
-is a property of the prepared picture. A model reference, a performed passage and an independent
-illustration are uses of material, not separate file classes.
-
-For a work carried by performance, including a short drama or an otherwise pure A-roll piece,
-prefer Script and semantic preparation. Script names meaningful, performable passages and events;
-the accepted performance supplies their actual time. This remains useful without MG: replacing a
-passage, revising dialogue, placing Caption or directing sound can preserve the same relationships.
-A Segment need not equal one camera shot or one speaker turn.
-
-In this spoken chain, A-roll is the performance carrying the Script passage. Its picture can fill
-the frame, move, disappear beneath evidence, or be absent in an audio-only performance. That role
-specifies neither a source aspect ratio nor a visual component type.
-
-Material identity, performance role and current appearance answer different questions. One placed
-performance can supply several simultaneous views; a later replay of its source can have independent
-playback. Direct cuts and continuous movement are authored ways to change presentation. The Timeline
-keeps the performance's time, while each visual owner determines its use on the Canvas. A layout
-change can reuse the same accepted material and semantic evidence.
-
-A **SemanticTake** combines one Segment's prepared media with its local word and boundary positions.
-The current Timeline Take input is this value. Independent images, video inserts and music instead
-enter the components that use them; they do not need artificial Script passages. A wordless performed
-Segment has real media and its boundary times. A standalone material transformation can finish with
-the transformed asset. [Media preparation](media.md) explains these input relationships.
-
-## One Timeline provides the work's time
-
-The **Timeline** holds the complete range and placed Takes. A Take's placement translates its local
-positions into program time. Gaps, overlaps and a range with no Takes are valid. A code-authored ending
-can extend past the last performance; a wholly authored animation uses the same Timeline.
-
-For an event that responds to a word or passage, retain the Script Moment or Selection. The component's
-Surface projects that reference through the actual Timeline to an Instant or Window. Independent
-rhythm can use authored clock positions, and motion can have its own duration. These all use the
-same program clock. [Timeline](timeline.md) owns placement; [Timing](timing.md) owns event expressions.
-
-Placed content is available before any presentation is selected. Timeline chooses no winning
-picture, transition or audible mix. An overlap supplies multiple sources; the presentation owns how
-they appear or sound. Independent Media, graphics and audio also use this Timeline to place events,
-including events attached to speech.
-
-## One Canvas provides the work's space
-
-The **Canvas** supplies picture dimensions and coordinates. A Frame locates a destination; fitting
-maps a source's real extent into it. Components own their internal layout and motion. A presenter
-and diagram can share a scene, while an independent title remains a peer. Frames may overlap, nest,
-move or extend beyond the canvas.
-
-Canvas is a geometry value, not a second asset store or a central layer tree. Each visual contribution
-publishes its own appearances and internal trees. A **Present** owns an appearance's lifetime and
-paint order; that order determines what covers what. [Spatial layout](spatial.md) owns geometry;
-[component design](component-design.md) owns useful visual scope.
-
-Time authority and visual scope are independent choices. One scene can follow several semantic
-events; separate components can share one Moment. Giving a scene the whole canvas does not require
-fixed-second choreography. Giving an image a semantic Window does not turn it into a Take.
-
-## Present existing content or supply independent content
-
-Two content relationships recur in ordinary authoring:
-
-| Content | Present already authored content | Supply content for this contribution |
-| --- | --- | --- |
-| Picture | Performance obtains footage and source positions from Timeline. | Media receives images, prepared video or compositable surfaces. |
-| Sound | Sound obtains placed audio from Timeline. | Audio Track receives independent audio-bearing material. |
-| Text | Caption obtains Script display content and its performed timing. | Typography/Text receives independent writing. |
-
-These are useful starting points. A project scene can combine placed footage, independent assets,
-text and projected events when they share behavior. The same video can carry a performance here and
-serve as an independent replay elsewhere. [Tracks](tracks.md) routes the actual presentation choices.
-
-Performance, Sound and Caption separate available content, timed **Uses**, and the **Style** applied
-by each Use. Later matching Uses replace the treatment locally; independent Tracks can coexist.
-The content retains its original timing under these choices. Each family owns its rendering and
-content-specific rules.
-
-Keep three times distinct: program time locates the appearance, source time identifies the media
-frame, and local animation time determines the presentation's state. A Take placed at second 5 is
-at source second 2 at program second 7, even if its viewport only becomes visible then. Performance
-and project scenes can consume this mapping directly. An independent Media Item instead declares
-its own source and playback policy. [Performance](performance.md) explains continuous presentation.
-
-An original and a cutout are explicit material choices. If the placed Take contains only the cutout
-picture, a presentation needing its original background must receive the retained original as an
-input. No Style can recover pixels absent from its material.
-
-## Components express the relationship worth preserving
-
-A component owns shared behavior. Its public inputs connect actual dependencies and useful directing
-choices: selected assets, important events, placement or a treatment that the work needs to vary.
-Decorative geometry and a fixed local design can remain in its implementation. A one-off scene is
-ordinary production work; reuse and cross-project distribution are separate decisions.
-
-Critical internal events need their own semantic relationships when they answer different parts of
-the performance. Making only the scene's outer Window semantic does not keep several word-linked
-actions synchronized. Interpolation and local motion can then follow those events without exposing
-every number as a control. [Component design](component-design.md#let-meaning-drive-the-behavior)
-explains that boundary; [Track authoring](track-authoring.md) explains the public implementation path.
-
-Visual components publish VisualTracks; audible contributions publish AudioTracks. Film explicitly
-selects the wanted contributions and combines them with Timeline and Canvas into a **Composition**.
-Including picture does not include sibling sound automatically. A whole scene can publish both
-outputs while keeping their assembly explicit. Source nesting, component scope, paint order and
-execution dependencies describe different relationships and need not have matching boundaries.
-
-## Give each part the direction it can realize
-
-The Agent keeps the complete creative intention and translates it into each part's effective inputs.
-
-| Recipient | Direction it can realize |
-| --- | --- |
-| Image generation | Visible appearance, setting, camera relationship, activity and reference facts. |
-| Video generation | Dialogue, performance, physical interaction, camera behavior and intended cuts. |
-| Voice generation | Wording, vocal character, delivery and suitable voice references. |
-| Visual/audio components | Selected content, layout, events, treatments and mix. |
-
-A planned diagram may call for a person framed on the right. Give the image request that visible
-camera relationship; give the diagram component its placement and events. Translate later MG or
-screen-writing needs into the picture facts the image model can produce. The full Treatment remains
-the director's context. [Image direction](../playbooks/craft/image-direction.md),
-[video direction](../playbooks/craft/video-direction.md), [voice direction](../playbooks/craft/voice-direction.md)
-and [Prompt Kits](prompt-kits.md) own those local decisions and templates.
-
-## Source describes the work; Run selects this execution
-
-The Author Source connects content, media requests, components and deliverables. Recipes provide
-authored values. A Run chooses public Outputs as **Targets** and can supply alternative **Candidates**,
-such as a file or an exact earlier Result Output. The selected dependencies determine what executes.
-
-For a layout revision, keeping a compatible SemanticTake preserves the performance and alignment
-while the presentation recomputes. Keeping only its generated video lets normalization and alignment
-recompute too. Keeping the old Composition would also preserve the old layout. Choose the reuse
-boundary according to the current edit. [Authoring](authoring.md#reuse-produced-work-explicitly)
-owns that judgment; [Runs](runs.md) owns the syntax.
-
-A **Build** executes the selected work. Its **Result** retains completed public Outputs, including
-usable products completed before a later failure. A new Build uses prior work only through explicit
-selection. [Builds](builds.md) owns execution, recovery and retrieval.
-
-## Runtime and Studio serve the authored work
-
-External work is expressed as a Need. Model and processing packages define capabilities; Providers
-implement them through Endpoints selected by a Runtime Profile. Tools, credentials and capacity belong
-to those execution choices. [Environment](../environment/profile.md) owns setup; [rendering](rendering.md)
-owns requesting an encoded output from the Composition.
-
-Studio inspects the same selected Run. A package's Companion connects recognizable entities and
-useful controls to their actual authored facts. Editing a shared Style or semantic event affects
-its consumers; a local parameter changes its own owner. Studio does not require every internal
-detail to become editable. [Studio](studio.md) explains use and writeback;
-[Companion authoring](studio-companions.md) explains project integration.
+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.
+
+## Materials acquire roles through use
+
+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.
+
+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
+
+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.
+
+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.
+
+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.
+
+## Contribution does not classify media
+
+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.
+
+```text
+SynchronizedMedia + Window -> Visual Clip
+SynchronizedMedia + Window -> Audio Clip
+
+NarrativeAlignment + LocalDomain + Window -> absolute Narrative time
+```
+
+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.
+
+## Canvas is the picture coordinate
+
+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.
+
+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.
+
+## Visual and Audio Tracks own ordinary occurrences
+
+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.
+
+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.
+
+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.
+
+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.
+
+## Components express relationships worth preserving
+
+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.
+
+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.
+
+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.
+
+## 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.
+
+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.
+
+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.
+[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 14eca6bc..fdf11475 100644
--- a/skills/hypit/references/production/timeline.md
+++ b/skills/hypit/references/production/timeline.md
@@ -1,74 +1,83 @@
-# Placing Takes on the Timeline
-
-Use this when placing prepared Takes, leaving passages for MG, or creating a work without speech.
-[Media preparation](media.md) produces local SemanticTakes; [Script syntax](script-syntax.md)
-names Selection/Moment identities. [Timing](timing.md) projects them; [Tracks](tracks.md) explains presentation.
-
-A Timeline contains the complete time range and the Takes placed within it. Semantic anchors exist
-where those Takes supply them. Prefer this semantic organization for performance-led work, including
-pure A-roll and short drama without MG. A meaningful passage can span shots or speakers; its actual
-performance gives the authored words and boundaries time. For an event responding to speech, bind
-to its Selection or Moment; use authored time for independently directed rhythm. Both belong to this
-one Timeline.
-The project's reference `TIMELINE.md` records observations and their meaning; the production
-`time:Timeline` declaration places the new work's material. Reference times locate evidence, while
-production placements determine the rendered work.
+# 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.
+
+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`.
```svml
<import as="time" from="@hypit/timeline-author@1"/>
<time:Clock id="clock" frame-rate="30"/>
-<time:Timeline id="program" clock={clock} end="content.end+2s">
- <time:Take source={opening.take} at="2s"/>
- <time:Take source={explanation.take} at="previous.end+3s"/>
- <time:Take source={closing.take} at="previous.end-12f"/>
+<time:Timeline id="program" clock={clock}
+ end="latest(answer.end,outro.end)">
+ <time:Window id="opening" from="start" for={opening-media.extent}/>
+ <time:Window id="answer" from="opening.end" for={answer-media.extent}/>
+ <time:Instant id="claim" at="answer.end-12f"/>
+ <time:Window id="outro" from="claim" for="3s"/>
</time:Timeline>
```
-First omitted `at` means zero; later omitted `at` means the preceding Take's end. Omitted Timeline
-`end` means the latest end of all Takes. Ordinary sequential assembly therefore needs only the
-Clock and Take references. Material lengths resolve when preparation finishes; generation can run
-concurrently while these placement relations wait for their inputs.
-
-`previous.end` refers to the preceding declaration. `content.end` is the maximum of all placed
-ends, even when the latest-ending Take is not the last declaration. Absolute positions such as `20s`
-work too. `end="30s"` reserves a fixed complete duration; `end="content.end+2s"` reserves a tail.
-Reordering Take declarations changes placements that depend on `previous.end`, including omitted
-`at` values, and can therefore move later dependent Takes.
-Seconds, milliseconds and frames must resolve to exact frames on the Clock. All complete Takes fit
-inside the authored extent. Take placement retains native speed and local semantic evidence.
-
-The current `time:Take source` accepts a SemanticTake, not an arbitrary image, video or audio file.
-Independent assets enter their own components with this Timeline as their time context. Each placed
-Segment and its token/anchor identities occur once in a Timeline. To show the same footage again as
-an independent replay, use Media; a separate performed Script occurrence has its own Segment.
-Timeline holds placed material and evidence; it publishes no picture or sound by itself.
-
-A gap contains no performance source. A wordless Segment instead has actual prepared media, as with
-someone dancing. MG can occupy either passage according to the intended picture. Pure MG needs no
-placeholder media or Script:
+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.
+
+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(...)`.
+
+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:
```svml
<time:Timeline id="animation" clock={clock} end="30s"/>
```
-The output `.timeline` supplies Film and component contexts through `timeline={program.timeline}`.
-Component Surfaces, Fragments and Producers use that same Timeline; shared temporal helpers
-project both literal times and Script references against it.
-Timeline exports only `.timeline`. [Sound](sound.md) presents its existing audio and supplies an
-AudioTrack to Film. Its ordinary Style chooses the last declared active audio source; a project
-Style can explicitly mix sources. Material remains available independently of its presentation.
-
-[Performance](performance.md) obtains existing footage from the Timeline. Ordinary Media Items take their own
-assets. Caption obtains existing words, while Typography takes authored text. A custom scene can
-consume the same placed footage and projected event times. New display Windows preserve the source
-frame corresponding to the current Program time; moving a viewport does not restart playback.
-
-Overlapping Takes make both sources available. They do not prescribe a dissolve or choose a picture.
-The ordinary Performance Style places its sampled layers in declaration order; for a coordinated blend or layout,
-use a scene that owns that behavior. Simultaneous Caption Cues retain their spoken intervals; use
-Role-based styles or separate Caption presentations when their placement should differ.
-
-Caption also receives a Script-derived CaptionDocument: the document supplies display text and cue
-structure, while Timeline supplies placed timing. Independent B-roll and music receive Timeline for
-placement and their own assets for content; semantic preparation is needed for a performed Script,
-not for every asset used in a composition.
+## Unknown material length is an ordinary dependency
+
+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.
+
+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 meaning, media and presentation separate
+
+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:
+
+```text
+NarrativeAlignment + LocalDomain + Window -> absolute Instants/Windows
+SynchronizedMedia + Window -> visual / audio occurrence
+Timeline -> finite absolute range only
+```
+
+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.
+
+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.
+
+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.
diff --git a/skills/hypit/references/production/timing.md b/skills/hypit/references/production/timing.md
index 4d2862a2..04dc3eff 100644
--- a/skills/hypit/references/production/timing.md
+++ b/skills/hypit/references/production/timing.md
@@ -1,96 +1,80 @@
# Timing authored relationships
-Read this when deciding when a component acts or what moving it in Studio should change.
-[Script syntax](script-syntax.md) names speech relationships; [Timeline](timeline.md) places prepared
-Takes and declares the complete work. This page owns the common author-facing time forms.
-The consuming package's vocabulary declares which forms its Surface actually supports.
+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.
-## Choose time from the relationship
+## Start from the production decision
-For speech-led work, bind a reveal to the Moment it answers and a covering picture to the Selection
-it explains. The accepted SemanticTake locates those identities in its media; Timeline placement
-carries them into the whole work. Rewording or changing the performance can then preserve what the
-picture follows. Reference timecodes document observations, not the new performance's timing.
+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.
-Authored animation can instead place messages or state changes on a clock and give them an intended
-reading rhythm. It needs no invented Script or media-backed Segment. A spoken Moment can also trigger
-a component whose internal animation uses authored durations. The trigger, its offset and the length
-of its response are separate decisions; one video can use all of them.
+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:
-## Express an Instant or Window
+```svml
+<semantic:Projection id="story-time" narrative={story} timeline={film.timeline}>
+ <semantic:Map alignment={speech.alignment} domain={speech-media.domain} window={film.speech}/>
+ <semantic:Window id="proof" selection={story.selection.proof}/>
+ <semantic:Instant id="claim" moment={story.moment.claim}/>
+ <semantic:Instant id="answer-end" segment={story.segment.answer} boundary="end"/>
+</semantic:Projection>
+```
-Surfaces that expose Hypit's shared temporal vocabulary accept the forms appropriate to their role.
-A Window occupies an interval:
+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.
+
+## Window forms
+
+Surfaces using the common Window vocabulary accept one of these forms:
| Form | Result |
| --- | --- |
-| `during="program"` | The complete program Window. |
-| `during={story.segment.hook}` | The Segment's Window. |
-| `during={story.selection.proof}` | The Selection's Window, including its authored affinities. |
-| `at={story.moment.claim} for="8f"` | A Window beginning at a Moment and lasting eight frames. |
-| `at="2s" for="12f"` | A Window beginning two seconds into the film and lasting twelve frames. |
-| `until={story.moment.claim} for="250ms"` | A 250 ms Window ending at a Moment. |
-| `start="program.start" end="moment.cue" moment={story.moment.claim}` | A Window composed from two explicit endpoints. |
-
-Each Window uses one complete form. Explicit endpoint expressions can use `program.start`,
-`program.end`, `selection.start`, `selection.end`, `segment.start`, `segment.end`, or `moment.cue`,
-with the corresponding semantic reference supplied alongside it. They can also use a clock position
-such as `1.5s` or an offset such as `selection.start - 2f`. Frames and milliseconds are integers;
-seconds may be fractional.
-
-An Instant names one point:
+| `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. |
+
+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.
+
+## Instant forms
+
+An event component uses one Instant:
| Form | Result |
| --- | --- |
-| `at={story.moment.claim}` | The authored Moment. |
-| `at="2s"` or `at="12f"` | A point on the film clock, in seconds or frames. |
-| `at={story.selection.proof} boundary="start"` | The Selection's chosen boundary. |
-| `at={story.segment.hook} boundary="end"` | The Segment's chosen boundary. |
-| `instant="program.start + 8f"` | An explicit clock expression. |
-| `instant="moment.cue + 12f" moment={story.moment.claim}` | Twelve frames after the Moment, following it when the delivery changes. |
+| `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. |
-`at="12f"` locates an event; `for="12f"` gives an interval its length. Frames use the selected
-film clock. Semantic projection keeps the event's Script identity alongside its resolved frame,
-so its authored relationship remains available for later changes.
+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.
-A particular Surface may deliberately expose only some of these forms. Its vocabulary reports the
-attributes it actually accepts; the shared spelling does not grant every component every temporal
-behavior.
+## Name only what needs a name
-## Choose what a later edit changes
+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.
-Dragging a direct Selection or Moment changes that identity in Script. Every Track consuming it
-then follows the changed relation. The authored time form determines what the gesture changes:
+## Editing
-| Time form | Timeline editing |
-| --- | --- |
-| `during={story.selection.proof}` | Move both boundaries by the same number of semantic stops; the duration can change. Trim either boundary independently. |
-| `at={story.moment.reveal}` on an event | Move its Moment anchor. |
-| `at={story.selection.proof} boundary="start"` or `boundary="end"` on an event | Move only that Selection boundary. |
-| `at={story.moment.reveal} for="8f"` | Move the Moment, or trim the trailing edge to change the duration. |
-| `until={story.moment.reveal} for="8f"` | Move the Moment, or trim the leading edge to change the duration. |
-| `at="2s" for="8f"` | Move the clock position, or trim the trailing duration; `until/for` works conversely. |
-| `instant="moment.cue"` or `instant="moment.cue + 2f"` with a bound Moment | Move the local offset while retaining the Moment; an omitted offset starts at zero. |
-| `start="..." end="..."` | Trim one endpoint's time expression, or move both by the same frame delta. Referenced Script markers stay in place. |
-
-A semantic stop is a distinct frame position occupied by word or structural boundaries. Select a
-semantic marker to see its exact anchors; when several share a frame, the Inspector offers the
-choices supported by its editable consumers. Word starts, word ends and structural boundaries
-are all eligible anchors; a pause can belong to
-either neighboring interval. Direct Segment/Program spans follow their structural boundaries
-without timeline dragging. The executed time authority determines the available gestures, and
-the Companion connects them to the component's entities and Source bindings.
-
-Clock-based dragging writes the changed value or offset in whole frames at the current frame rate.
-Unedited expressions retain their units: `2s` keeps its duration across frame-rate changes, while
-`60f` keeps its frame count. Direct semantic dragging changes the Script anchors instead.
-
-Script marker moves use the [same semantic affinities](script-syntax.md#bind-meaning-to-script-identities)
-as authored markers. Writeback removes and inserts the moved markers while preserving unrelated
-source whitespace, words, punctuation, pronunciation and display attributes. A shared Selection or Moment remains one relationship:
-editing through any consumer updates its other consumers according to their own projections.
-
-A component's Companion exposes the gestures it can write back to the authoring source.
-[Studio](studio.md) explains the editing interface; [Track authoring](track-authoring.md) explains
-using the shared temporal helpers in a project component. The installed `@hypit/temporal-markup`
-package owns exact parsing, projection and write-target APIs.
+Studio follows the producer of the value:
+
+- 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 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.
+
+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.
diff --git a/skills/hypit/references/production/track-authoring.md b/skills/hypit/references/production/track-authoring.md
index b48215eb..8562c96a 100644
--- a/skills/hypit/references/production/track-authoring.md
+++ b/skills/hypit/references/production/track-authoring.md
@@ -10,10 +10,11 @@ and project package ownership. [Caption authoring](caption-authoring.md) covers
## Start with the author-visible behavior
-Prefer semantic inputs when the component responds to the words or performance. A comparison can occupy
-a Selection; a verdict can trigger a Moment; the whole board can live for a Segment. Expose those
-choices on the Surface and pass their projected Windows or Instants to the implementation. This
-keeps the component useful when a new performance changes the pace. Expose separately meaningful
+Prefer domain-produced time when the component responds to words or performance. A Narrative
+projector can turn a comparison Selection into a Window, a verdict Moment into an Instant, and a
+Segment into a board lifetime. Expose ordinary absolute values on the component Surface and pass
+them to the implementation. This keeps the component useful when a new performance changes the
+pace without coupling it to Narrative. Expose separately meaningful
internal events as well as the outer lifetime. The [event-versus-animation boundary](component-design.md#let-meaning-drive-the-behavior)
explains why a single semantic Window cannot replace several word-linked triggers. In an authored animation,
content events carry their own reading rhythm. Their Instants and Windows enter the same component
@@ -27,47 +28,47 @@ the component more usefully than a long list of decorative parameters.
This existing answer-strip vocabulary illustrates a concrete choice:
```svml
-<emoji:Track id="answers" timeline={speech.timeline} canvas={canvas}
- style={answer-style} placeholder={question-icon} during="program">
+<emoji:EmojiReveal id="answers" timeline={speech.timeline} within={canvas.bounds}
+ style={answer-style} placeholder={question-icon} during="timeline">
<emoji:Item id="known" icon={known-icon} preset="true"/>
- <emoji:Item id="surprise" icon={answer-icon} at={story.moment.reveal}/>
-</emoji:Track>
+ <emoji:Item id="surprise" icon={answer-icon} at={story-time.reveal}/>
+</emoji:EmojiReveal>
```
Its outer Window owns visibility; source order owns slots; preset answers exist at the beginning;
-each Moment changes only its slot and the answer persists. A chart or scoreboard can instead own
+each activation Instant changes only its slot and the answer persists. A chart or scoreboard can instead own
repeated updates or simultaneous events.
-## Keep selection, projection and consumption distinct
+## Keep domain projection and consumption distinct
-Script names meaning: a Selection, Segment or Moment. The Timeline supplies where that
-event falls after its prepared media is placed. The consuming component's Surface lowers its authored timing
-form into a projection subgraph, which resolves an Instant or Window in the program's frame space.
-The component's own Fragment and Producers then decide what to do with that value.
+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
+Producers decide what to do with them.
```text
-Script Selection / Segment / Moment + Timeline
- ↓ component Surface creates projection
+Narrative relationship + Alignment + LocalDomain + Window
+ ↓ Narrative projector
Timeline + Window / Instant
- ↓ component Fragment / Producer consumption
+ ↓ generic component consumption
media occupancy, graphic state, sound or effect
```
-This separation lets one Moment drive an answer reveal, a short sound and a flash. Each consumer
-receives its own appropriate projection, but all refer to the same authored event. Changed speech
-moves the event without asking each component to search for a word or inspect the Script parser.
+This separation lets one projected Instant drive an answer reveal, a short sound and a flash.
+Consumers can share that one value. Changed speech moves the upstream event without asking each
+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 word-bound events without switching time
+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
content children with their own events and a picture drawn entirely in code.
-For a Window consumer, `during={story.selection.example}` can take both semantic boundaries.
-`at={story.moment.answer} for="8f"` starts a short effect at a Moment. An Instant consumer may accept
-`at={story.moment.answer}` with no duration because it owns a state transition. Read the actual
-Surface: identical-looking `at` attributes do not imply identical consumption. [Timing](timing.md) describes the shared author
-forms; the component chooses which of them fit its behavior.
+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.
+[Timing](timing.md) describes the shared forms.
## Separate lifetime, activation and persistent state
@@ -87,11 +88,15 @@ 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 the Timeline's existing placement model
+## Use absolute time without turning Timeline into a media container
-The [Timeline](timeline.md) places intact prepared Takes at native speed. Sequential placement,
-head/interior/tail space and simultaneous Takes share the same data type. A project scene consumes
-its range, media samples and semantic events through ordinary projection helpers.
+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.
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
@@ -100,9 +105,10 @@ and a material change establishes truthful local evidence.
## Make spatial decisions equally explicit
-CanvasSpace identifies the coordinate system. SpatialFrame, anchors, extents and fitting describe
-where content goes and how its intrinsic shape occupies that place. RegionTimeline supplies authored
-per-frame regions in a chosen Canvas. These are distinct from Timeline, which owns the complete time range.
+Canvas identifies the final raster viewport. SpatialFrame, anchors, extents and fitting describe
+where content goes and how its intrinsic shape occupies that place. Region Track supplies authored
+per-frame regions already resolved in the program picture plane. These are distinct from Timeline,
+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
@@ -116,7 +122,8 @@ Declare the new package in the project's `packages/` and ordinary package config
installed `@hypit/hypit/author-kit` README for the public package boundary and inspect a close installed sibling for
the relevant implementation, rather than depending on a monorepo example directory being present.
`@hypit/interview-emoji-reveal` demonstrates persistent Moment-driven state; `@hypit/ranking`
-demonstrates reveal Windows and settled rows; `@hypit/media-track` demonstrates occupancy and Handoffs.
+demonstrates reveal Windows and settled rows; `@hypit/visual-track` demonstrates ordinary Clip
+occurrences with independent Window, Frame, fit and source-time relations.
Ranking provides a complete example in the installed Distribution. Its `packages/ranking/README.md`
links the relevant files: `surface.ts` projects authored time, `fragment.ts` connects typed inputs,
@@ -124,11 +131,12 @@ links the relevant files: `surface.ts` projects authored time, `fragment.ts` con
`packages/ranking-studio/src/index.ts` turns the same program into editor entities. Follow the part
that answers the current question. A new component may use fewer operations or different state.
-The Surface exposes author intent and lowers its supported temporal forms through shared projection
-helpers such as `createTemporalWindowProjection` and `createTemporalInstantProjection`. The Fragment
-wires those projections, the shared Timeline/Canvas and authored values into the component's
-Producers. The Producer consumes the resulting time and geometry and owns the visual/state behavior;
-Studio consumes that published meaning for presentation and editing.
+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
+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
treatment in Source or Recipe where the work needs those choices. A one-off component can own fixed
@@ -151,18 +159,19 @@ The useful pieces of a project package are:
| Optional Studio Companion | Project meaningful editor entities, real parameter bindings and temporal lineage without changing video rendering |
Resolve the Track's `timeline` through `resolveTemporalContext` and wire `context.timeline.ref`
-directly to its Timeline input. Words and source footage are available where prepared Takes provide
-them. The visual Producer consumes Timeline and projected times, not Script syntax.
-
-For each Window, call `createTemporalWindowProjection`; for an event, use
-`createTemporalInstantProjection`. Pass the resolved context, the child element
-and `resolveReference`. Preserve all returned `records`, `components` and `fragments`, and wire the
-returned `ref` into the domain Fragment. The common `at` accepts a Moment or an authored duration
-from program start. Selection and Segment boundaries use `boundary="start"` or `boundary="end"`.
-A Moment needs the semantic context that locates its Script anchor.
-
-Keep each child's `subjectId` meaningful to the component while qualifying graph ids by its owning
-Track, so multiple instances can coexist. A finite create/append/finalize graph supports any authored
+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.
+
+For each Window, call `createTemporalWindowConstruction`; for an event, use
+`createTemporalInstantConstruction`. Pass the resolved context, the child element and
+`resolveReference`. Preserve all returned `records`, `components` and `fragments`, and wire the
+returned `ref` into the domain Fragment. Window consumers support `during` or exactly two of
+`from`, `until`, and `for`; Instant consumers support `at`. These accept completed temporal values
+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
live in `@hypit/hypit/temporal-markup`; the `@example/chat-scene` package demonstrates authored and semantic events on one Timeline.
@@ -183,7 +192,7 @@ Pass asset references and exact font data through declared inputs. A visual Prod
files, call GVI, run ffmpeg or choose a Provider. If an external preparation operation is needed,
represent it separately through its capability; its result becomes another input.
-A component-owned sound can be a peer AudioTrack output; alternatively the Source can place a sound
+A component-owned sound can be a peer Audio Track output; alternatively the Source can place a sound
on the same Moment. Neither choice requires a Track to inspect another Track's private state.
Document which Outputs are public, including useful deterministic program values for inspection.
@@ -205,11 +214,12 @@ checks around activation and exit are more useful than snapshots of every implem
Also check a second instance, a differently sized Frame and direct seeking into the middle when
those exercise the new behavior.
-## A reusable performance presentation
+## A reusable relation spanning Clips
-When the behavior presents existing Timeline footage, [Performance Styles](performance.md) offer
-an occurrence model with broad and local Uses. A Style binds a typed fragment's additional inputs;
-each Use supplies Timeline, Canvas and its original Window. The fragment exports a VisualTrack.
-This supports project-owned HTML behavior and explicit extra events or material without introducing
-a new Track protocol. A larger scene that coordinates footage and independent graphics can remain
-its own component. Both paths use the same rendering capabilities.
+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.
diff --git a/skills/hypit/references/production/tracks.md b/skills/hypit/references/production/tracks.md
index 04c901c6..11961ca7 100644
--- a/skills/hypit/references/production/tracks.md
+++ b/skills/hypit/references/production/tracks.md
@@ -1,67 +1,54 @@
-# Choosing and composing contributions
+# Choose and compose contributions
-Read this to choose how content enters the picture or sound. [System](system.md) explains the
-relationships; [media preparation](media.md), [Timing](timing.md) and [spatial layout](spatial.md)
-own the shared inputs. A new shared behavior belongs in a [project component](component-design.md).
+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).
-## Choose by content relationship
+## Choose by relationship
-| Content relationship | Useful starting point | Published contribution |
+| Relationship | Starting point | Output |
| --- | --- | --- |
-| Present footage already placed on Timeline | [Performance](performance.md) | `.visual` |
-| Supply an independent image, prepared video or compositable surface | [Media](media-presentation.md) | `.visual`, optional `.audio` |
-| Present audio already placed on Timeline | [Sound](sound.md) | `.audio` |
-| Supply independent audio-bearing material | [Audio Track](audio-presentation.md) | `.audio` |
-| Present Script's display words at their performed times | [Caption](caption-presentation.md) | Fine publishes `.track` |
-| Supply a title, label or other independent writing | [Typography/Text](fonts-and-text.md) | Package-owned; Typography publishes `.track` |
-| Coordinate content through a new layout, state or motion | [Project component](track-authoring.md) | Its declared VisualTrack and/or AudioTrack outputs |
+| 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 |
+| 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 |
-The table routes common relationships; it does not define a closed list of visual roles. A board,
-effect or whole scene is a component whose behavior owns its inputs and outputs. Images, text and
-video can share one scene. Film receives their ordinary visual and audio contributions.
+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.
-## Present a performance without reauthoring its playback
+## Reuse one normalized source without binding picture and sound
-For pure A-roll as well as mixed work, place prepared SemanticTakes on the [Timeline](timeline.md),
-then use Performance and Sound for the picture and audio the work needs. A broad Style can cover the
-whole program; local Uses change its treatment. Caption independently joins Script display content
-to that same timing. A performance need not remain visible to supply speech and semantic events.
+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:
-An audio-only Take supplies no picture. A wordless performed Take can supply material and Segment
-boundaries. A gap has no Take. These facts remain independent of graphics occupying that interval.
-Independent material can also occupy the full canvas; size and transparency do not decide its role.
+```text
+normalized media + Window + visual sampling -> Visual Clip -> VisualTrack
+normalized media + Window + audio sampling -> Audio Clip -> AudioTrack
+```
-A new scene can consume `projectTimelineMedia` to keep placed footage at its current source frame
-while coordinating it with other content. [Performance](performance.md) explains Styles;
-[component visuals](component-visuals.md#compose-video-and-graphics-in-one-browser-program) explains
-owning a larger scene. Media receives separately supplied material when that is the intended use.
+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.
-## Let events and shared behavior determine organization
+## Let events and behavior determine organization
-A Media picture can cover a Selection, a sound can follow a Moment, and a board can retain its answer
-after a reveal. All use the same Timeline, with timing forms supported by their own Surfaces.
-[Timing](timing.md) owns those forms; [Track authoring](track-authoring.md#keep-selection-projection-and-consumption-distinct)
-owns implementing their projection and consumption.
+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.
-An outer Window describes a component's lifetime. Internal events can have their own semantic
-triggers, and the resulting state may persist. A scene's single lifetime does not justify moving all
-its meaningful events to fixed percentages of that Window. Use the [component design principles](component-design.md#let-meaning-drive-the-behavior)
-to separate event relationships from local animation.
+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.
-Shared movement or state can justify a shared component. Independent contributions may stay peers
-while consuming the same Moment. A Track is not required for each asset, each Script Segment or each
-rectangle, and creating a component does not require publishing a package outside the project.
+## Assemble only what the film needs
-## Assemble the intended contributions
+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. Timeline establishes the
-complete extent; components establish appearances and their paint order. Include sibling audio
-explicitly when wanted. A silent covering picture leaves the selected voice audible; selecting the
-same voice through multiple audio contributions can duplicate it.
-
-Film child order does not move a picture to the front. Each Present has its authored stacking and
-its internal element tree. An internal transform, mask or transition can keep related content
-together while independent Presents overlap it according to their own stacking.
-
-[Rendering](rendering.md#assemble-the-picture-and-sound) shows assembly and full/range delivery.
-[Review](review.md) judges the selected work, including performance, boundaries and the complete mix.
+[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.
diff --git a/skills/hypit/references/production/visual-clips.md b/skills/hypit/references/production/visual-clips.md
new file mode 100644
index 00000000..f40a10bd
--- /dev/null
+++ b/skills/hypit/references/production/visual-clips.md
@@ -0,0 +1,96 @@
+# 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.
+
+## The ordinary relation is one Clip occurrence
+
+Visual Track has one base child form:
+
+```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
+```
+
+```svml
+<visual:Motion id="photo-push">
+ <visual:Pose at="start" scale="1.08" easing="ease-out"/>
+ <visual:Pose at="end" scale="1"/>
+</visual:Motion>
+
+<visual:Track id="picture" timeline={program.timeline}>
+ <visual:Clip id="speaker" media={speaker-media.media}
+ during={program.speaker} frame={layout.full} z="10" fit="cover"/>
+ <visual:Clip id="photo" image={product} extent={product-extent}
+ during={story-time.example} frame={layout.detail} z="20" fit="contain"
+ treatment={look.visual.still} motion={photo-push}/>
+</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.
+
+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`.
+
+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.
+
+## 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.
+
+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.
+
+```svml
+<visual:Clip media={shot.media} during={story.outro} frame={layout.full} z="10">
+ <visual:Map target-at="end" source-at="end" rate="1"/>
+</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.
+
+## Relationships spanning Clips are components
+
+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.
+
+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.
+
+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.
+
+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.