@autoaiai/aicut 0.1.11 → 0.1.13

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

@@ -1,259 +0,0 @@
-# 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

@@ -1,143 +0,0 @@
-# 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

@@ -1,94 +0,0 @@
-# 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

@@ -1,126 +0,0 @@
-# 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.