@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/hypit/references/creation/script-and-time.md

@@ -0,0 +1,259 @@
+# Script and semantic time
+
+Read this when deciding the target wording, pronunciation, performable passages and the meanings
+that picture and sound should follow. It also covers estimated delivery duration and wordless passages.
+[Script syntax](../production/script-syntax.md) owns the authoring forms;
+[Timing](../production/timing.md) owns their projection into the work.
+
+[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 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 media, domains and alignment evidence.
+
+## Script is the target's sole verbal authority
+
+`<script>` contains the words the target video will say. It contains no reference timecodes, media,
+visual Style parameters, prompts, or provider decisions. Semantic word attributes such as
+`useful{emphasis}` can identify a word's role for a Caption family. Brief may preserve required claims and Treatment may describe
+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; 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;
+- a **word attribute** gives a Caption family an authored role on one displayed word;
+- a **Selection** names the span of meaning an element serves, such as a demonstration covering an
+  explanation or a comparison held through a claim;
+- a **Moment** names an event such as an answer or verdict, where graphics, sound or effects can
+  respond together. The component decides how the resulting state continues.
+
+```svml
+<script id="story">
+  <hook>
+    <HOST> @{claim!} I made the @{proof}<API | A P I> || work overnight.@{/proof}
+  </hook>
+</script>
+```
+
+Here the viewer reads `API` while the performance receives `A P I`. The pair is one indivisible
+Alignment Unit. `||` ends one on-screen Caption Cue after that unit and lets the next Cue begin with
+`work`; `proof` remains one semantic range, and `claim` is a semantic point that other layers can use.
+
+A Cue is a timed block of displayed speech, not a line of text. Its Caption family and Recipe may
+wrap that block over one or more lines, reveal or highlight its words, and give the block an entrance,
+exit or handoff. Segment boundaries and Role turns already separate Cues. Caption Use windows can change a
+Style midway through a Cue while preserving its content and original word times.
+Use `||` when the same Segment, turn and Style still needs another deliberate reading handoff. The
+[Caption craft](../playbooks/craft/captions.md#design-cue-rhythm-with-the-caption-system) owns how the
+picture, language, family and Recipe shape that decision.
+
+[Script syntax](../production/script-syntax.md) owns the exact forms, display/speech projections,
+spacing, grouping and marker affinities. Use those forms to express the choices above.
+
+## Write the intended pronunciation
+
+Choose pronunciation while writing the Script. For coined names, unfamiliar brands and abbreviations
+whose reading needs direction, use Dual Text to keep the intended display spelling and give the
+performer a clear spoken form. Write that form as readable words, syllables or letter names in the
+performed language. Familiar word sounds, phonetic respellings and homophones can make an unfamiliar
+name's intended sound concrete while its display spelling stays intact. Keep ordinary spelling when
+it already expresses the intended reading; an English name inside Chinese speech does not
+automatically need a phonetic replacement. Choose the reading for this language and character,
+retaining the user's chosen display spelling.
+
+### Choose the sound the spelling should carry
+
+These examples illustrate authored pronunciation choices, not generation results verified for every
+model. The spoken column is the literal text supplied through `.speech` or inside `.dialogue`:
+
+| Intended reading | Script fragment | Caption displays | Spoken text |
+| --- | --- | --- | --- |
+| Name the letter S | `<S\|ess>` | `S` | `ess` |
+| Say each letter of CSS by name | `<CSS\|see ess ess>` | `CSS` | `see ess ess` |
+| Spell out an abbreviation using separated letters | `<API\|A P I>` | `API` | `A P I` |
+| Say SQL as the word “sequel” | `<SQL\|sequel>` | `SQL` | `sequel` |
+| Give a coined name familiar syllables, when “zoo no” is the chosen reading | `<Zuno\|zoo no>` | `Zuno` | `zoo no` |
+| Give a name a chosen Mandarin homophonic reading | `<Lumi\|露米>` | `Lumi` | `露米` |
+
+Letter names, letter sounds and an acronym pronounced as a word are different choices. `ess` names
+S; it does not ask for a sustained /s/ sound. Likewise, `sequel` chooses one reading of SQL; use the
+intended letter names when the character should spell it out instead. Choose natural phrasing for
+the whole expression rather than inserting artificial pauses between every letter or syllable.
+
+Phonetic notation, including IPA, can guide a model that understands it. Script forwards the written
+form literally; it does not interpret IPA or expose a phoneme-control API. The spoken projection also
+feeds duration estimation and semantic preparation, so choose a representation usable by that production's
+speech path. Any model-specific pronunciation feature belongs to that model's documented inputs.
+Keep a reading aid such as `ess` on the spoken side; prose instructions such as “pronounce this as”
+belong in performance direction when needed, not among the words the Script asks the character to say.
+
+### Carry the chosen reading through the work
+
+```svml
+<script id="story">
+  <opening>
+    <HOST> This app connects through an <API | A P I>.
+  </opening>
+  <closing>
+    <HOST> The same <API | A P I> works here too.
+  </closing>
+</script>
+```
+
+Each pair applies to that occurrence. Carry the chosen spoken form into every occurrence of the
+name, including other Segments, so separately generated performances receive the same direction.
+The right-hand wording reaches the model through the Segment's `.dialogue`; Caption keeps the
+display spelling. Settle these readings before estimating the Script's duration and requesting its performance.
+
+The same distinction helps Chinese copy express numbers and names clearly. For example,
+`今年<2026|二零二六>年` displays the year compactly while specifying how it is said;
+`只要<¥19.9|十九块九>` chooses a conversational price reading. Choose the spoken form for this
+sentence's meaning and delivery. Estimating the Segment with `--language zh` then uses that spoken
+wording, including the syllables hidden behind its compact numeric display. Caption retains the
+authored simplified or traditional characters; transcription supplies timing rather than rewriting
+the displayed Script.
+
+## Choose performable passages
+
+Supply the Segment's `.dialogue` to the speaking prompt; it includes Role labels and the chosen
+pronunciation. `.speech` supplies pronunciation without Role labels for duration estimation or speech-only
+requests. The Caption view preserves the display wording. These are projections of one Script,
+so revising the words does not require maintaining another copy in a prompt or subtitle file.
+[Script projections](../production/script-syntax.md#use-the-scripts-deliberate-projections) shows the
+references and a two-speaker example.
+
+Script also represents passages without speech:
+
+```svml
+<script id="story">
+  <empty></empty>
+</script>
+```
+
+`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 associated normalized
+media can provide its local duration. When a consumer needs that identity projected through the
+actual media, NarrativeAlignment can have an empty unit array while still mapping the Segment
+boundaries; the Segment's existence alone does not require Alignment.
+The same Timeline and Track timing vocabulary apply to a wordless passage or an entire
+piece made from prepared media. The empty tag itself declares neither a zero-length interval nor a duration.
+For an interval made only of component animation, use Timeline placement and extent instead; it
+needs no media-backed Segment. Spoken, wordless-media and graphics-only passages can share one work.
+
+Choose Segment boundaries from natural production passages and delivery length, not from every
+picture cut. One Segment and one generated clip can carry several speaking turns, camera cuts or a split-screen
+conversation. One continuous narration can carry many B-roll changes through Selections. Edited UGC
+can deliberately use several generated clips driven by the same character-and-scene image; a natural cut is
+often part of its appeal. A Role change or `||` does not require another generation.
+When retained recorded speech carries the passage, a file cut changes that performed material but
+does not automatically create a Segment. Several retained stretches can form one passage; distinct
+passages can use separate performance clips. Write the Script for the final performed words and,
+when downstream relationships need their positions, align the prepared result on its own local clock.
+
+## Time an authored animation
+
+For speech-led work, a graphic's timing usually follows what it explains. Preserve that relationship
+in Script: a reveal belongs to its Moment, and coverage belongs to its Selection. Rewriting the
+argument or changing the performance then carries the design into the target's actual timing.
+Reference seconds document what you observed; the target Script expresses what the new graphic follows.
+
+A chat animation, diagram or kinetic-text piece can instead be drawn entirely by components. Its
+messages and changes still carry meaning; the author chooses when the audience receives them and
+how long they need to read. Keep content and the named time values that drive it together in Source.
+An event can have an identity such as `question` or `reveal`, produced by a Timeline child or a
+standalone `time:Instant`, without 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. Ask the Narrative projection to publish that Moment as an absolute
+Instant. If the design needs a lead or lag, derive a separate named `time:Instant` with an explicit
+offset, then pass the chosen result to the component. The event's trigger and its entrance duration
+are different choices: `at={answer}` locates the answer; ten frames can give its arrival a particular
+character.
+
+## Estimate before choosing durations
+
+For a new or revised A-roll performance, choose time from the target's words, delivery, and action.
+The reference timeline remains useful for understanding rhythm and relationships; the new performance
+establishes their actual timing. Even unchanged words may take a different amount of time with a new
+speaker or delivery.
+
+`hypit estimate` is the creation-time command for `@hypit/speech-estimate`. It counts pronunciation units and
+estimates how many seconds they need at the chosen language and pace, using local computation:
+
+```bash
+hypit estimate path/to/source.svml --segment opening --language en --pace normal
+hypit estimate --text "You expect me to type every coffee?" --language en --pace normal --rounding ceil
+hypit estimate path/to/source.svml --segment opening --language zh --pace fast --rounding round
+```
+
+Choose `--pace slow|normal|fast` from the intended delivery: conversational explanation may suit
+`normal`, while brisk, tightly cut social delivery often suits `fast`. The CLI prints the actual
+units-per-second rate; `--rate` lets you choose it directly. Mandarin counts Han characters as
+approximate syllables and embedded English by syllable; English counts syllables rather than words.
+Set `--language zh` for Chinese copy, including copy with English product names, and estimate from the
+pronunciation side of Dual Text with `--segment`.
+
+The density includes ordinary phrasing pauses. `--padding` reserves additional time for an intended
+reaction, demonstration or held pause. Keep related performances at a coherent delivery density. Initial
+estimates can retain fractions with `--rounding none`. `ceil` rounds upward to a whole second, while
+`round` chooses the nearest one. Most video requests use whole seconds; choose the final literal with
+the selected model's supported values and the intended performance in mind.
+
+An energetic performance can still give a dense explanation room to breathe. Use the reference's
+pronunciation-unit count over its spoken passages to inform a candidate rate, then choose for the target's language,
+terminology and actions. Inspect the effective density after rounding each request: fitting every
+line into the shortest supported duration can make the whole delivery rushed. Keep the chosen rate
+and meaningful padding with the production's direction so later Segments follow the same decision.
+
+Let that estimate inform the shape of the passage. A short line may belong with the next response,
+benefit from a little fuller wording, or leave room for a meaningful action. A long passage may read
+better with tighter copy or a split at a natural change of thought. Preserve the intended meaning and
+energy while finding a performable shape, then estimate the affected wording again. The
+[Generated video direction](../playbooks/craft/video-direction.md#size-the-request-around-the-delivery)
+applies this judgment to the selected model's request range.
+
+The estimate balances the intended speaking density and sizes generation; it supplies no timeline
+anchors. Once a generated clip is accepted, normalize it and use its actual extent to construct an
+equal-length Timeline Window. When Caption, B-roll, MG, Effects or another consumer needs word
+positions, align the actual speech to its Script Segment and map that evidence through the
+domain/Window relation. The literal duration answers how much media to request. Alignment answers
+where words occurred inside accepted media; it does not reproduce an estimated distribution of words
+and is not required when no downstream relationship consumes those positions.
+
+For a wordless Segment, choose the requested duration from the action, music or visual rhythm.
+Speech-rate estimation has no role there; the resulting media still determines its Segment span.
+
+## Bind meaning to Script identities
+
+For a picture, Caption treatment, MG state, sound, or effect that belongs to spoken meaning, author a
+Selection or Moment, reveal it through an explicit Narrative Projection declaration, and pass the
+resulting named Window or Instant to the consumer. Use a direct named time declaration for genuinely
+clock-based or speechless design.
+
+Choose an anchor by the event it names, including which side owns a pause. For adjacent B-roll,
+one Selection can end where the next begins; for a held reaction, a range can include the silence
+before the next word. [Marker affinities](../production/script-syntax.md#bind-meaning-to-script-identities)
+express these choices through word and structural boundaries. [Timing](../production/timing.md)
+explains projecting those identities into named Instants or Windows, adding deliberate offsets,
+and what a later Studio edit changes.
+
+Reference archives keep original seconds and explain which original words or content events an item
+serves. The target Source names the intended relation against the target Script. After the target's
+actual audio is aligned, the Timeline supplies its frames. Do not copy a reference timestamp into
+the target or preserve an incidental lead/lag unless that offset itself is part of the design.
+
+## Connect reference understanding to audiovisual composition
+
+Timing seen in Studio or a real Result may expose one of several different problems. A wrong Cue or
+semantic anchor changes Script. A sound performance that changes the intended rhythm may change the
+duration choice or Treatment. A correct Selection rendered badly changes the component or Recipe. An
+unusable generated clip changes its prompt, reference, Candidate, or shot design. Put each correction
+where its fact is owned.

package/skills/hypit/references/creation/transformations.md

@@ -0,0 +1,143 @@
+# Transforming a reference into a target
+
+Read this when a user brings a reference and asks for their own version: another person, object,
+world, performance, story, or audience. Several changes can belong to one creative intention.
+
+Look at the supplied material and think about the reference together with the user's request. What
+makes the original compelling, and how can that appeal belong to this new person or product? Keep
+the reference's particular humor, visual relationships, and rhythm in view as you develop the target.
+The reference archive describes the original; Brief records the user's intention; Treatment explains
+how the new piece will work. Useful discoveries can change any part of that understanding as the work
+develops.
+
+## Preserve the role, then recreate the form
+
+Recreate the reference's semantic timing intentions in the target. If a ranking portrait appears
+when a player is introduced and settles with the judgment, bind those events to the target's own
+Script. A different speaker or rewritten argument will change the seconds; the relationship can
+remain. Keep an explicit clock interval when that interval itself is part of the intended design.
+
+Before replacing an object, understand the role it plays in the work. A presenter may also appear as
+an avatar, a voice, a B-roll subject, a phone image, and the identity inside an MG system. A product
+may be a prop, a screen, a demonstration, a claim, and the final CTA. Transform the role across every
+real manifestation; do not stop after changing its most obvious pixels.
+
+The target need not copy a form that no longer fits. Preserve the purpose of an action, composition,
+or callback while directing a form that makes sense for the new body, product, platform, and viewer.
+A cat can perform confidence through a planted pose, gaze, tail, or framing without literally copying
+a human hand gesture. A product with no screen can demonstrate the same benefit through a different
+piece of evidence.
+
+Useful transformation lenses include:
+
+- **subject or identity** — who carries the narrative role and everywhere that identity appears;
+- **product or brand** — product truth, use, props, UI, logos, colors, proof, offer, and CTA;
+- **Script, language, or CTA** — meaning, speech rhythm, on-screen wording, demonstrations, and the
+  timing relationships that follow the new words;
+- **platform, duration, or aspect** — which story functions survive, compress, expand, or need a new
+  composition;
+- **visual or tonal style** — art direction across generated shots, Caption, Typography, MG, Effect,
+  and Audio, without erasing the reference's useful structure;
+- **adding or removing a system** — redistribute the job formerly done by that system rather than
+  leaving a narrative hole;
+- **multiple references** — state which function comes from each reference and resolve conflicts in
+  Treatment instead of blending every surface detail.
+
+These lenses are prompts for thought, not fields to complete. Follow the relationships the actual work
+contains.
+
+## Reshape an event from footage
+
+Some adaptations are recognizable through an unfolding event rather than any one subject's pixels.
+A stylized direct-address performance, dance phrase, fight, moving camera view, or mishap seen by a
+fixed camera may depend on particular timing and physical relationships. These are useful places to
+look for temporal evidence: discover what carries the reference's appeal, from performed delivery
+and reaction to movement, contact, camera position and payoff.
+
+The target may change a person, object, setting, spoken words, sound, visual world, or several of
+these together. Changing the person is common; a narrow substitution may leave most other
+relationships intact. When a new body, object or story changes what an action means, reshape the
+action to serve the target's intention. Brief and Treatment hold the requested change and the new
+creative answer; the source footage remains evidence rather than a ready-made target timeline.
+That evidence may remain observational, or a selected excerpt may become an actual generation input
+when the target must preserve or transfer its temporal behavior. These are different decisions.
+
+In a comic speaking reference, an unusual camera angle may work together with role-played vocal
+phrasing, expression and gesture. Put the intended words in Script, choose whose voice belongs to
+the target, and direct how the visible performance delivers the joke. A supplied portrait establishes
+appearance, not the voice or delivery. [Voice direction](../playbooks/craft/voice-direction.md) owns
+casting; [video direction](../playbooks/craft/video-direction.md#let-footage-carry-temporal-behavior-that-matters)
+owns when and how a selected source excerpt should condition the new shot.
+
+## "Make this with my face"
+
+Suppose the user supplies a portrait and a football Ranking video. The jokes concern the players, so
+the spoken argument and comic reveals may already suit the new presenter. Bring the user into the
+camera image with the reference's teasing confidence, useful framing, and room for the board. Keep
+the full [image craft](../playbooks/craft/image-direction.md), directing the supplied person's appeal
+and presence with the same care as any leading performer in this work. That image can carry all
+ordinary talking clips and supply the person's other appearances.
+
+A joke about the original presenter's appearance or personal story needs another look: decide how
+its setup and payoff fit the new casting and Brief. The new person may invite a different delivery or
+a better version of the joke. A supplied pet might express the same confidence through a planted
+pose, gaze, or comic authority. Let the new character make the work feel inhabited.
+
+The portrait supplies visual identity; [voice direction](../playbooks/craft/voice-direction.md)
+uses supplied audio or a voice chosen for the target performance. The original photo's setting and
+pose may give way to the shot the video needs. Use [reference relationships](../playbooks/craft/generated-dependencies.md)
+to decide where the supplied image enters that production.
+
+## "Use my product"
+
+Suppose a podcast recommends a bottled product, while the user wants to promote their budgeting app
+and supplies receipt scanning as its real benefit. The casual recommendation, skeptical partner, and
+satisfying demonstration can still carry the exchange. The opening split screen, complementary
+views, and speaker-colored Caption may still give it its recognizable shape.
+
+The new conversation might turn on "You expect me to type every coffee?" A phone demonstration of
+scanning a receipt answers that objection. Now the host holds a phone, the covering footage shows the
+app in use, and the graphic reveal supports the same moment of understanding. Script, action, imagery,
+and CTA grow from what this product actually offers. Supplied product images and UI establish its
+appearance; the user's facts and relevant product material establish its claims. Resolve important
+gaps from available material or with the user while continuing to develop the creative idea.
+
+When both person and product change, consider their relationship together: why this person recommends
+it, how the partner responds, and what makes the encounter engaging. Treatment holds that creative
+answer; Source expresses its words, references, and semantic relationships.
+
+## Treat generation as ordinary production
+
+Think of the image model as a broadly informed painter, the video model as a broadly informed camera
+crew and performer, and audio generation as a broadly informed sound team. “Real” is an aesthetic
+direction—iPhone capture, natural light, documentary movement, room tone—not a claim about where the
+asset came from. The normal task is to create the target media.
+
+External references become essential when public world knowledge cannot determine exact identity:
+the user, a private or obscure product, a proprietary interface, an exact Logo or data display. An
+accepted generated image, video or sound can then become authority for later work.
+
+Prefer reference-conditioned video generation when identity, art direction, composition, or product
+continuity matters. The input guides the shot without having to appear as its literal first or last
+frame. Use keyframe-constrained generation when the endpoint image itself is part of the designed
+continuous change. Use text-only generation when the shot benefits from variation and needs no exact
+visual anchor. These are control meanings; package and Provider support remains owned by their public
+documentation.
+
+## Keep media dependencies shallow and useful
+
+Generate actual work: the main A-roll camera image, the reverse angle, a B-roll image, a product close
+up, or a component slot. The first accepted presenter image will often already be the main A-roll
+camera image. Another A-roll view can be generated from it by describing the new camera relationship,
+eye line, recurring objects, light, and what naturally changes when the camera faces the other way.
+The shared world lives in the relationship between useful shots, not in an abstract scene plate.
+
+An independent identity asset or location image is useful when the work itself needs it independently.
+Otherwise, avoid chains of intermediate pictures that exist only to feed the next generation. For a
+single shot split by a model's duration limit, reuse the same accepted visual authorities for each
+part unless the cut itself is designed around a literal boundary frame.
+
+Carry accepted media into the composition through Source and Run Candidates. Use Studio and rendered
+Results to develop Caption, MG, B-roll coverage, effects and sound around those assets. If a generated
+item fails its intended role, improve the responsible prompt, reference relation or shot design before
+deciding on another authorized request. Reconsider Treatment when the creative answer itself changes.

package/skills/hypit/references/playbooks/craft/b-roll.md

@@ -0,0 +1,94 @@
+# Material-led pictures and B-roll
+
+An image or video can carry a passage's visual answer: evidence for a claim, a place to inhabit, an
+action to understand, a contrast or a joke. B-roll is a common editorial use of that material while
+a performance carries the passage's words and time. The same materials can also lead the picture
+through a narrated explanation or a speech-free sequence. Choose their role from what the viewer
+needs to see, rather than from whether the source is a still, a moving clip or a person.
+
+## Give the material a reason to appear
+
+Creator-led video often shows the speaker's life while their performed words continue: working,
+studying, travelling, using a product or reacting in another situation. Those pictures make the
+person and world more tangible. The person visible in a lifestyle image or silent clip may be the
+same person whose voice is heard; the placed performance still owns the words. A different passage
+may use a visible speaking performance whose own delivery carries the words. [Voice and performance](voice-and-performance.md)
+owns that distinction.
+
+An image can hold a product fact while the speaker makes a claim. A moving demonstration can show
+the action that proves it. A screenshot can make an interface state readable. One well-chosen
+picture may carry the thought more clearly than a new shot for every noun. When the work needs new
+material, [image direction](image-direction.md) or [video direction](video-direction.md) owns its
+creation; this page owns why and how it appears in the work. When the screen itself carries the
+explanation or evidence, [screen demonstrations](screen-demonstrations.md) owns that directing choice.
+
+## Choose the relationship to the thought
+
+**Exact correspondence** serves a claim whose meaning depends on a particular picture being
+visible at that point. Give that image or clip the semantic Window the claim needs. A brief
+display can use part of a longer source; the generation request's duration does not set its
+display duration.
+
+**A visual thought across several pictures** can convey a habit, history, process or attitude.
+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.
+
+A generated multi-scene clip needs direction for scene order and meaningful actions. The
+`@hypit/seedance-kits/broll` Kit's `story` Text can express that relationship for Seedance; its
+package README owns the tested wording and edit choices. A direct image, an existing video or
+independently arranged media may serve the same visual purpose without that Kit.
+
+## Compose material and performance in the same picture
+
+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 audio
+continues. Its location and paint order follow the composition, not its B-roll name.
+
+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. 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
+the Canvas, Frames, fitting and crop that realize the chosen arrangement.
+
+A video's location sound or action sound can contribute to the mix when it helps the moment.
+Picture placement by itself does not replace the performed speech; [sound and mix](sound-mix.md)
+owns how those audible contributions meet.
+
+## Let the picture enter and leave on its own terms
+
+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. 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.
+[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
+expose another view. [Script marker affinities](../../production/script-syntax.md#bind-meaning-to-script-identities)
+owns the exact shared-boundary forms; [review](../../production/review.md#make-the-composition-work)
+locates an unintended flash or gap. Watch the actual result: a nominally continuous Window cannot
+make an exhausted source or transparent frame fill the picture.
+
+## When material leads the whole passage
+
+A music-led montage, tactile process film or visual product explanation can make images and clips
+the main sequence. Choose cuts from the visual argument, physical action or musical phrase. A close
+view earns its change when it reveals what the wider view could not; a quiet contact or settling
+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) 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.

package/skills/hypit/references/playbooks/craft/caption-tracking.md

@@ -0,0 +1,126 @@
+# Caption above a moving head
+
+Read this when the user's reference visibly uses Caption that follows a speaking person's moving
+head, or the user asks for that treatment. Ordinary Caption uses its family's layout and Style
+placement; the presence of a face does not by itself call for head boxes. The optional measured or
+authored regions answer where this particular speaker's words should appear in the actual picture.
+
+## Resolve who, where and when
+
+Script Role identifies who says the Cue. The intended view of that person in the final composition
+determines where the Cue follows them; GVI face-track ids do not establish identity. The speech and
+the directed Caption treatment determine when it appears. In ordinary turn-taking, the previous
+speaker's Caption hands off as the next speaker starts. Their face remaining visible is not a reason
+to keep their earlier words on screen.
+
+Measure whichever available picture lets those relationships be mapped accurately:
+
+- A supplied or prepared clip gives source-local positions that must follow its placement,
+  playback, crop and any moving view into the composition.
+- A composed view already contains its camera framing and program time, provided graphics do not
+  obscure the person being measured.
+
+Retain the relation between the measured source and its use. A source timestamp can change meaning
+after trim or retiming, and a face box can move after crop or reframing. A presenter shrinking into an
+inset needs positions that follow that actual transformation. When the same person appears in
+several views simultaneously, choose the view this Caption follows. Fine accepts one region per Role
+per frame; several simultaneous text placements need an explicitly authored presentation.
+
+Leave room for the complete Cue and nearby graphics. A correctly measured head can still be an
+awkward place to put a long phrase; the work may instead use ordinary Caption placement there.
+
+## Read face observations
+
+The worked method used Google Video Intelligence. Its face feature can return bounding boxes when
+`FACE_DETECTION` is requested with `includeBoundingBoxes` enabled; facial attributes are unnecessary
+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
+Region Evidence, 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)
+expresses `timeOffset` relative to the input video and the rectangle as `normalizedBoundingBox`.
+Use all relevant observations, not just the first box printed by a sample program.
+
+Treat the returned face tracks as candidate observations. Inspect representative frames from each
+track and associate useful fragments with the intended Script Role. A detector track is not a global
+person identity: a cut can split one guest across several tracks, and one shared shot can contain
+several people. Combine the fragments that visibly belong to the Role in final program time. Selecting
+the first or largest face alone can attach the guest's Caption to the interviewer.
+
+## Map observations into the composition
+
+Transform the useful observations into ordinary project data, with these decisions explicit:
+
+- **Clock:** sample the observations on the Timeline's frame clock using the actual source playback
+  mapping. For prepared media on the same clock at native speed, add its actual placement start,
+  including any gap or overlap. Apply any source trim or rate change when measuring other footage.
+  Final-video measurements already use that rendered program's clock.
+- **Geometry:** convert detector edges to `[x, y, width, height]` using width `right - left` and height
+  `bottom - top`. If measurement used another resolution, crop, inset or split-screen panel, map the
+  box through that actual placement before normalizing it to the final Canvas. Update this mapping
+  through a moving or resizing view; a single fixed rectangle cannot describe that movement.
+- **Head extent:** expand the face region to include the relevant hair, hat and desired clearance.
+  For face `(x,y,w,h)`, authored padding fractions can produce
+  `(x - pL*w, y - pT*h, w*(1+pL+pR), h*(1+pT+pB))`. Choose those fractions from the visible head;
+  there is no universal face-to-head multiplier. Keep the resulting region valid inside the Canvas.
+- **Missing observations:** make any interpolation or smoothing an explicit external preparation
+  choice within a continuous shot and the same person. Inspect it, stop at cuts and occlusion, and
+  write `null` when no usable region exists. Fine does not invent a missing box.
+
+Each Role track's final array has exactly one box or `null` per program frame. Keep the actual array
+in a project Recipe such as `tracking.svs`. A project script can perform the transformations using
+explicit source, clock and geometry inputs. Changing the camera use can require remapping positions.
+
+## Place only the intended speaker's Caption
+
+Script and Caption already connect a Role's words to their timed Cue; the region input supplies the
+head position for the frames where this treatment follows them. A `null` region also hides that
+Role's Cue on that frame. Use the Cue's presentation window or `null` regions to end its appearance
+at the intended handoff, including when a Style's tail would otherwise leave the old words over the
+next speaker. When the person is absent, obscured or in another camera view, choose whether the
+Caption ends or uses an authored ordinary placement. Neither a detector track nor the mere presence
+of a listening face extends someone's speech.
+
+[Caption presentation](../../production/caption-presentation.md) owns Style coverage and hiding.
+A Role with no region evidence keeps ordinary Style placement; a `null` inside an existing series hides
+the Cue rather than switching placement automatically. A deliberate tracked-to-ordinary change can
+use explicit Caption Uses or separate Tracks with the same Script and Timeline.
+
+For example, this is a three-frame data-shape illustration, not a ready timeline for a real video:
+
+```svs
+heads.default {
+  series: [
+    {"id":"GUEST","regions":[[0.12,0.09,0.20,0.26],null,[0.13,0.10,0.20,0.26]]}
+  ];
+}
+```
+
+## Connect the placement to Caption
+
+```svml
+<import as="region" from="@hypit/region-evidence@1"/>
+<region:Evidence 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:Caption>
+```
+
+The Region Evidence 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/region-evidence` and `@hypit/caption-fine` READMEs own the exact data behavior.
+
+## Inspect the actual placement
+
+Use Studio or [snapshots](../../production/snapshots.md) to inspect the current picture around
+camera changes and speaker handoffs. Check the first and last frames of each tracked Cue, the whole
+Cue's clearance above hair or hats, top-edge clipping and collisions with graphics. Play the passage
+with speech to judge jitter, wrong-person jumps and reading rhythm. When source timing or visual
+presentation changes, remap the affected observations rather than carrying stale coordinates forward.