--- title: Tracks description: Peer track components — captions, media, typography and authored audio. --- Every audiovisual contribution entering the final composition is a peer **Track**. Tracks are flat (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 source-neutral document produced by Script and a replaceable Style family: ```text Script → CaptionDocument + NarrativeCaptionBinding Binding + NarrativeProjection → complete Unit CaptionTiming authored Cues + CaptionTiming + Uses → family presentation schedule → VisualTrack ``` ```svml ``` `@hypit/caption` owns the common CaptionDocument contract, including ordered Words, correspondence Units and authored Cues, plus complete-unit Selection/Role queries, Style assignment and the flat timing join. `@hypit/caption-fine` is one Style family: it presents those Cues and owns their geometry, glyph/Cue/Pill Paint and layered local motion. ### caption-fine:Style A Style is a rendering intent resolved from one package-owned SVS Recipe: ```svs caption.primary { stack-order: 70; x: 0.5; y: 0.88; width: 0.84; height: 0.22; anchor-x: center; anchor-y: bottom; size: 58; line-height: 0.96; letter-spacing: -0.5; word-gap: 14; align: center; block-align: end; inline-size: fixed; wrap: word; max-lines: 2; max-words-per-line: 4; direction: ltr; fill: #FFFFFF; opacity: 1; stroke-color: #09090B; stroke-width: 2; shadow-color: #000000; shadow-opacity: 0.72; shadow-x: 0; shadow-y: 3; shadow-blur: 8; glow-color: #FFFFFF; glow-opacity: 0.12; glow-blur: 8; gradient-from: #FFFFFF; gradient-to: #93C5FD; gradient-angle: 120; long-shadow-color: #111827; long-shadow-opacity: 0.35; long-shadow-distance: 8; long-shadow-angle: 45; background: #09090BCC; border-color: #FFFFFF20; border-width: 1; padding: 16 24; radius: 18; karaoke: trail; karaoke-transition: wipe; active-fill: #FFD54A; active-box: current; active-box-continuity: isolated; active-box-background: #FFD54ACC; active-box-padding: 4 8; active-box-radius: 8; active-underline: current; active-underline-color: #FFFFFF; active-underline-thickness: 3; active-underline-offset: 5; cue-enter: spring; cue-enter-frames: 4; cue-enter-start-scale: 0.75; cue-exit: none; cue-exit-frames: 0; atom-reveal: all; active-response: pop; active-response-frames: 5; active-scale: 1.08; lead-frames: 4; tail-frames: 4; handoff: cut; } ``` ```svml

``` The required `font=` edge carries one byte-reproducible `FontStackRef`. Family, weight and style exist only on that edge; each fallback retains its own exact face metadata. Fine rejects a Style without that stack instead of falling back to machine fonts. Another Caption package may define a different rendering family without changing the common CaptionDocument contract. Fine's properties are orthogonal: normalized placement and anchor; layout and typography; base/active solid or gradient glyph Paint; stroke, shadow, directional long shadow, glow and underline; Cue/Pill Paint; three independent glyph/Pill/underline activation channels; and layered Cue, Alignment-Unit, active-response and loop motion. Missing optional dimensions resolve deterministically to no decoration or motion. Unknown properties are rejected. The package groups those properties as **Where**, **How** and **When** in its Surface declaration, so Studio can present the same author contract without maintaining a Caption-specific property list. `lead-frames` and `tail-frames` form an explicit visible Schedule around the spoken Cue; `handoff: cut` prevents adjacent visible envelopes from competing, while `overlap` preserves both. Neither form changes the Word frames used by Karaoke. `karaoke` is `off`, `current` or `trail`; `karaoke-transition` is `step` or `wipe`. Timing is always whole-Alignment-Unit timing already proven by Caption. A normal one-word unit therefore highlights per word, while a Dual Text unit remains one indivisible visible unit. Fine never guesses internal time. `active-box` is independently `off`, `current` or `trail`. `active-box-continuity: isolated` paints one capsule per activated Alignment Unit; `joined` turns a trail into one ordered prefix whose background is continuous on each real browser line. Thus trail-colored text with a current-only Pill is one Recipe—not a second renderer. With `wrap: word`, Fine wraps between complete Alignment Units and falls back inside a single over-wide display unit so it cannot escape the Region. `max-words-per-line` constructs explicit rows; when `max-lines` is present, a Cue that would construct more rows is rejected instead of having its text or Paint clipped. Cue boundaries come from Script segments, turns and authored `||`. Fine is the uniform-flow family: every token follows the same Recipe and may differ only by time, index or play state. A Cue with authored internal roles—different font/layout groups, full-frame inversion, tearing or cross-clause composition—requires another Caption package rather than a hidden Fine exception. CJK dialogue can be written directly. For a display-only emoji that still follows speech timing, author the correspondence explicitly, such as `<🌐 | globe>`; the system will not invent a spoken word for a bare symbol. ### 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

``` `||` 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. A timed Use names an already resolved absolute Window through `during`. ## Visual Clips and B-roll 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 ``` ### visual:Track and visual:Clip 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 A clean vertical product film: the written script becomes semantic regions, then those regions assemble into a finished video. ``` `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. A Narrative projection may publish `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 `` 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 | |---|---|---| | `image={...}` + `extent={...}` | Blob + authored pixel extent | A durationless still image | | `media={...}` | `SynchronizedMedia` | Connect an explicitly prepared timed source directly | | `surface={...}` | `CompositableSurfaceRef` | Connect an alpha-aware still or timed surface directly | A generated or imported video Blob reaches a Track through ``, which inspects it, selects its streams and puts them on one frame domain; its `.media` output is what `media=` connects to. `audio="none"` carries the picture alone, and `audio="default"` carries the source's own sound, 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.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. A `Clip` consumes `SynchronizedMedia`; normalize a declared or generated audio Blob first, then choose its exact program Window and source-time relation: ```svml ``` | Attribute | Required | Description | |---|---|---| | `Track.id` | yes | Stable Audio Track identity | | `Track.timeline` | yes | Timeline that defines the exact sample and frame domain | | `Clip.source` | yes | Explicitly selected and normalized `SynchronizedMedia` | | `during` | yes | A named absolute Window | | `source-time` or `Map` children | no | Reusable or inline partial target-to-source relation; omission is bounded partial identity | | `gain`, `fade-in`, `fade-out` | no | Explicit per-Clip mix values | The package performs no automatic extraction, normalization, ducking, or bus routing. Multiple 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 Static or timed text displayed on screen — titles, callouts, lower thirds. ```svml ``` ### text:Flow, text:Point and text:Path 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 EDIT MEANING, NOT TIMELINES ``` | Attribute | Required | Description | |---|---|---| | `id` | yes | Unique identifier | | `timeline` | yes | Absolute Timeline that owns the occurrence window | | `during` | yes | A named absolute Window | | `within`, `point`, or `path` | yes | Placement matching `Flow`, `Point`, or `Path` | | `style` | yes | Style compiled from an SVS Recipe plus exact font bytes | | `z` | yes | Absolute stacking for this occurrence; it is not part of Style | | form layout | no | `Flow` alignment/wrapping, `Point` anchors or `Path` margins and direction, written only on the matching occurrence | Each occurrence has one explicit placement form, one exact Style and one absolute time expression. `Flow` places flowing text inside a `SpatialFrame`: ```svml MEANING ``` | 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 | | timing | yes | `during={named-window}` | | placement | yes | `SpatialPoint`, `SpatialFrame` or `SpatialPath`, matching the occurrence form | | `style` | yes | A `text:Style` compiled from an SVS Recipe plus exact font bytes | | `z` | yes | Absolute stacking for this occurrence | | form layout | no | Direct layout attributes declared by the selected `Flow`, `Point` or `Path` form | `speech.window` covers the complete Timeline. An authored Timeline Window or an upstream semantic, beat or other projection can supply any other ordinary absolute Window. The fine-text component does not know which domain produced it: ```svml EXACTLY THE RIGHT MOMENT ``` Graph-produced copy remains visible as an edge: ```svml EXACTLY THE RIGHT MOMENT ``` 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. 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 A ranking board animates an ordered list against the Script. The concrete container, item and Style vocabulary is package-owned. Ranking, Depth Stack and Comment Sticker are optional packages, not part of the default Hypit installation. Add the selected published version to the video's ordinary `package.json` and lockfile before importing it; inspect that installed package before authoring. | Container | Item | Style | |---|---|---| | `ranking:Column` | `ranking:ColumnItem` | `ranking:ColumnStyle` | | `ranking:TopThree` | `ranking:TopThreeItem` | `ranking:TopThreeStyle` | ```bash npm install @hypit/ranking ``` ```svml ``` ### The style tag Empty, and all three attributes required: `id`, `recipe` (an SVS Recipe) and `font` (a Font Stack or Font artifact). The recipe is validated against the selected component variant; a Recipe from another family is refused by name. ### The container tag | Attribute | Takes | |---|---| | `timeline` | the absolute Timeline the board is timed against | | `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 absolute Instant where the completed board settles. `TopThree` only | Use only the timing forms admitted by the selected package; do not infer a terminal or reveal model from another component family. Optional sounds and reveal phases are valid only when the selected package declares them. ### The item tags Each variant takes its own, at least one, and ids must be unique within a board. - **`TopThreeItem`** — `label` and item-owned absolute Instant `at` are required; `icon` and `stack` are optional. At most three. TopThree reveal order comes from these Instants' actual frame order. - **`ColumnItem`** — `label` (required) and `rank` (required, a positive integer that decides the numbered row and nothing else), optional `icon` and `stack`. Each item also owns its reveal time: `during` names the absolute Window when it prefers to appear, and `preset="true"` marks a row that starts already placed. Exactly one of the two — an item with neither, or with both, is refused by name. ```svml ``` **Output:** `{board.visual}` — a VisualTrack. A board given a sound also exports `{board.audio}`, an 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 an Instant. 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. ```bash npm install @hypit/depth-stack ``` ```svml ``` ### deck:DepthStack `id`, `timeline`, `within`, `frame`, `appearance` and `until` are required. `until` references a named absolute Instant, whether it came from a Narrative Projection or a direct time declaration. ### deck:Card A direct child of the stack, self-closing, at least one, and dealt in document order. | Attribute | Takes | |---|---| | `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 — a named absolute reveal Instant | | `appearance` | optional — its own Recipe, otherwise the stack's | | `label` | optional — a `deck:Label` record | ### deck:Label `id` and `font` are required. The copy is either the `content=` reference or the element's own text — give both and it is refused. `size`, `color`, `align`, `block` and `padding` are optional. ```svml ``` **Output:** `{deck.visual}` — a VisualTrack, an ordinary peer of every other Track in the Film. ## Comment stickers Social-style comment cards placed in a Frame: an avatar, an author, the comment itself, and an optional metadata line. ```bash npm install @hypit/comment-sticker ``` ```svml ``` `comment:Style` is empty and takes `id`, `recipe` and `font`, all required. The recipe carries the card's whole appearance — background, border, radius, tail, avatar, the three text rows, and the enter/hold/exit motion — and every key has a default, so a recipe may set only what it changes. `comment:Track` takes `id` and `timeline` for the complete work. `comment:Sticker` requires `id`, `frame`, `style` and `during`, which references a named absolute Window. Its copy is either the `comment=` attribute or the element's own text — both is refused. The optional `author`, `header` and `meta` each take a string or a Text reference, `avatar` takes an image, and there is no `z`: stacking order comes from the recipe's `stack-order`. ```svml