@aswless_854771076/ai_short_studio_cli 0.1.98 → 0.1.100

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/playbooks/craft/asset-and-shot-preproduction.md

@@ -0,0 +1,193 @@
+# Asset and shot preproduction
+
+Read this for reference-led recreation or a multi-shot generated narrative before writing final video
+prompts. Its purpose is to make identity, world, action and continuity explicit before paid video
+generation. It does not introduce a separate project state machine: keep decisions in the production's
+Brief, Treatment, project notes, assets and Author Sources.
+
+Use [Shot production contracts](shot-production-contracts.md) when writing the production's copyable
+`ASSETS.md`, `SHOTS.md`, ordered reference manifest and generation gate.
+
+## Complete the asset inventory first
+
+Inventory every visible character, prop, location and dressing element. Completeness means nothing
+visible is omitted from the production contract: narratively significant and continuity-bearing assets
+receive stable keys and versions, while ordinary one-use dressing is explicitly recorded inside its
+scene asset instead of becoming an independent prop asset.
+
+| Asset | Record and prepare |
+| --- | --- |
+| Character | canonical identity, aliases, face, hair, body proportions, makeup, costume signature, shoes, accessories, expressions, recurring voice and each persistent appearance version |
+| Scene | macro location, useful micro spaces, scale, fixed architecture, entrances and exits, camera sides, foreground/midground/background anchors, key-light source and direction, palette and important materials |
+| Prop | form, scale class, material, color, markings, ownership or carrying relationship and every persistent state such as open/closed, intact/damaged or full/empty |
+| Voice and sound | speaker identity, language, accent, pitch, timbre, pace, room perspective and any recurring environmental bed |
+
+Treat a change of costume, age, damage, contents, time of day or stable set dressing as a version, not
+as an informal prompt variation. Resolve missing identity, ownership, state and version decisions before
+storyboarding. Do not infer an exact age, unseen side, prop state or spatial relationship from a name or
+genre convention.
+
+## Produce selected asset boards
+
+Asset boards are reusable evidence, not a decorative contact sheet. Reference-led recreation selects
+new character, scene and prop boards for the visible continuity-bearing assets before final video.
+Original narrative work follows its own storyboard and optional asset-board rules.
+
+- A character board includes a face close-up, front/side/back full-body views and the approved costume,
+  footwear, accessories, makeup and useful expressions. A material change receives its own appearance
+  version derived from the selected base identity.
+- A scene board is normally empty of named performers and includes consistent multi-angle views, a
+  readable layout or axonometric view, entrances/exits, fixed anchors, key-light direction, palette and
+  material samples. Its views must describe one coherent space.
+- A prop board includes a clean principal view, front/side/back views and necessary construction details.
+  A changed state derives from the selected base prop and changes only the evidenced state.
+
+Inspect original-resolution boards for identity, geometry, version and accidental text before adopting
+them. Keep the selected file, its role and provenance with the production. A remote URL or task receipt
+alone is not an asset.
+
+The installed `@hypit/gpt-image-kits/asset-sheet` Prompt Kit provides character, scene and prop board
+treatments without making the board itself a workflow node.
+
+## Make each shot an atomic production unit
+
+One shot has one time and place, one continuous camera behavior and one principal causal action chain.
+Split independent contacts, locations, montage beats or unrelated actions. For tightly controlled social
+recreation, editorial units commonly last one to three seconds even when the selected model requires a
+longer generated request; preserve the useful handle and trim only after reviewing the complete output.
+
+Every shot should state:
+
+- the first readable state, action onset, contact or change, completed result and briefly stable tail;
+- character count, left/right and depth order, facing, gaze, movement and entry/exit edge;
+- held objects, hand ownership and prop state before, during and after contact;
+- camera side, axis, framing, lens character, movement curve and intended cut relationship;
+- key-light direction, exposure, color and scene anchors that must remain continuous;
+- exact dialogue, performed duration and native sound intent.
+
+## Choose the storyboard strategy before generating any board
+
+Before generating images or selecting a Provider, have the AI classify each shot's actual uncertainty:
+single-frame, temporal, narrative, blocking, action, choreography, scene-overview, scene-plan,
+scene-turnaround, director-track, comprehensive, or spatial previz. Record the evidence and the
+smallest selected type in the production plan. Do not let the image executor's compatibility value
+`board_type=shot-board` replace this decision; it is only the technical image-rendering path.
+
+## Produce the storyboard views required by the selected workflow
+
+Original short-drama shots require both a temporal storyboard and a shot board. Reference-led recreation
+uses selected assets and source-derived depth by default; a board is added only when a named detail or
+staging risk cannot be verified from those inputs and the prompt. The views have different purposes:
+
+| Board | Use it for |
+| --- | --- |
+| Single frame | a static composition, expression, decisive instant or literal first/last-frame anchor |
+| Temporal storyboard | successive states inside one continuous shot: action phases, camera path or planned countdown states |
+| Shot board | multiple narrative beats, speaker/listener coverage, blocking, several hands, prop contact or a relationship that needs readable staging |
+| Spatial previz | complex routes, fights, crowd geometry, axis risk, spatial reveals or a continuous camera move that still images cannot verify |
+
+A temporal storyboard describes one shot across time. A shot board explains coverage or staging. Do not
+use extra cells merely for visual variety. Review every cell for reading order and internal continuity,
+then review the board against adjacent shots.
+
+Multi-cell temporal and shot boards default to six cells. The director may choose fewer or more when the
+action, beat count or legibility requires it; record the chosen count and reason. A hard-to-reproduce
+detail—countdown readings, device states, exact poses, hand contacts or prop changes—must expose every
+required state in its own reviewed cell. Pass the selected board to the video model as a semantic image
+reference so it controls state and order without appearing as a grid in the result.
+
+When a multi-cell board is supplied as a semantic reference, explicitly say that cells communicate time
+and action order only. The generated video must be one full-frame moving image with no grid, borders,
+panel divisions, arrows, labels, numbers, paper texture, split screen or collage. Never use an entire
+multi-cell board as a literal first- or last-frame image; extract and approve the required cell instead.
+
+The installed `@hypit/gpt-image-kits/storyboard` Prompt Kit supports the single-frame, temporal and
+shot-board treatments above. Use spatial previz only when still boards cannot establish the route or
+camera relationship.
+
+## Bind a per-shot reference manifest
+
+Before compiling the model prompt, create one ordered reference manifest for the shot. Each entry names
+the selected file/version and one primary responsibility:
+
+| Role | Responsibility |
+| --- | --- |
+| `character-identity` | the matching character face, body, costume and appearance version |
+| `scene` | the matching location view, geometry, fixed anchors, light and materials |
+| `prop-state` | the exact prop identity and current persistent state |
+| `temporal-storyboard` | successive action states, camera path and reading order |
+| `shot-board` | coverage, blocking, staging and character relationships |
+| `depth` | source-derived spatial structure, subject motion and camera motion only |
+| `motion-previz` | non-recreation work may use reviewed route or choreography when the model and Provider can consume it |
+| `first-frame` / `last-frame` | non-recreation literal pixel boundaries; forbidden in the final recreation manifest |
+| `audio-reference` | source-language voice, delivery, emotion and acoustic perspective |
+
+Do not mechanically attach the complete asset library to every request. Select the approved asset views that
+know the current shot and fit the model's real reference limits. In recreation, never silently discard
+selected assets, depth or the video prompt; connect audio and a reviewed board when the shot plan requires
+them. The original short-drama storyboard gate remains separate. If the selected
+Endpoint cannot accept the full mandatory contract, choose another Endpoint before submission.
+
+For reference-led recreation, make and inspect the depth video before the final shot. Keep it separate
+from the character and setting boards. A grayscale depth reference supplies structure, motion and camera
+behavior; it does not supply appearance or native depth conditioning. It is mandatory in the default
+contract and cannot be replaced by prose.
+
+## Establish cross-shot continuity
+
+For each shot record a start and end state covering character positions and poses, screen direction,
+gaze, held objects, prop state, entry/exit edge, axis, camera side and key-light direction. Differences
+must be either an intended change with evidence or an unresolved conflict.
+
+For non-recreation work, use an accepted previous tail as the next first frame only when scene, camera
+setup, axis and physical state genuinely continue. A new angle, location, axis or intentional state jump
+should begin from its own approved visual plan. Recreation does not send original keyframes or generated
+tail frames as routine final references; its selected asset and depth files carry the approved continuity.
+
+## Compile for the selected model
+
+The prompt is part of the reference contract, not another media asset. Translate each manifest role into
+the selected model's syntax and preserve the actual submission order.
+
+- H3 uses the bundled H3 guide. Full-reference work uses Ref2VA labels and its six English sections;
+  dialogue, lyrics and visible story text keep their original language.
+- Seedance reference syntax belongs to the selected Endpoint. StarRouter uses independently ordered
+  `@图片N`, `@视频N` and `@音频N` labels; every video and audio Reference carries measured
+  `duration-seconds`. Other Endpoints and existing Kits may use `@imageN`, `@videoN` and `@audioN`.
+  Do not put any Seedance dialect in H3 prompts or H3 sections in Seedance prompts.
+- For an atomic Seedance recreation shot, `@hypit/seedance-kits/recreation-shot` compiles the ordered
+  manifest, shot, continuity, dialogue, native sound and approved visible-text contracts. Its wording
+  does not create references: connect the actual Resources in the same order. Seedance Surfaces default
+  `generate-audio` to `true`, including for wordless action; set it to `false` only when the Brief
+  explicitly requires silence or the selected Endpoint cannot generate audio. Record either waiver.
+- Visible dialogue defaults to joint picture-and-audio generation. Bind exact lines, measured delivery,
+  mouth action, ambience and physical sound in the same request; add an audio reference when the reviewed
+  shot plan and selected Endpoint require one. For a
+  multilingual source, label every turn with its detected and confirmed language code; do not translate
+  or normalize all turns to one file-level language.
+- Put exact countdown readings and other difficult changing states into separate cells of the selected
+  temporal storyboard. Approve the cells at original resolution, then connect that board as a
+  semantic reference to the video request and describe the exact state order and timing in the prompt.
+  Reject malformed output and revise the board or prompt before regenerating the shot.
+
+Do not use original source picture or audio to patch a failed generated shot when the Brief requires a
+complete remake. Do not paint over, inpaint, composite over, splice-repair or locally retouch generated
+video. Regenerate the smallest failing unit after changing its prompt, board, reference selection,
+continuity contract or model choice.
+
+## Stop before paid generation when evidence is incomplete
+
+Do not submit the final shot while any applicable item is missing:
+
+- the asset inventory has unresolved identity, version, ownership or state;
+- a selected character, scene or prop board is absent or unreviewed;
+- the shot contains several independent causal chains instead of one atomic unit;
+- a storyboard required by the selected workflow or a named risk has not passed review;
+- a recreation depth result or video prompt is missing, or a required audio reference is absent;
+- the reference manifest omits a required responsibility or exceeds Provider limits;
+- cross-shot start/end states conflict or rely on a stale previous tail;
+- prompt mode, model Surface and actual references disagree;
+- joint audio dialogue does not fit the requested duration.
+
+After generation, [Review](../../production/review.md) owns full audiovisual inspection and the decision
+to accept or regenerate the shot.

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/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 Take 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 Items 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 Sound
+continues. Its location and paint order follow the composition, not its B-roll name.
+
+For an independent picture, [Media presentation](../../production/media-presentation.md) supplies
+the image or prepared video, its Frame, appearance and playback. A still has a display Window
+without needing video conversion. [Performance](../../production/performance.md) presents footage
+already placed on the Timeline and retains its source position as its view changes. When material,
+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. The placed Takes and Sound establish whose
+words are heard while the visual composition chooses when views change.
+
+Choose the end by the thought, action and time needed to read the picture. A still remains present
+through its Window; a moving source also has its own playback span. Let a clip finish when its
+last action matters, or cut it where the work gains the better beat. Holding, looping or retiming
+is another expressive choice, not a consequence of the Window being longer than the source.
+[Media presentation](../../production/media-presentation.md#keep-display-time-and-source-playback-distinct)
+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) holds performed Takes, gaps and directly authored
+intervals. 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/using-vvicat-ai-short-studio-cli/references/hypit/playbooks/craft/caption-tracking.md

@@ -0,0 +1,125 @@
+# 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 clip or prepared Take 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
+RegionTimeline, 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 a prepared Take 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 track keeps ordinary Style placement; a `null` inside an existing track 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 {
+  frame-count: 3;
+  tracks: [
+    {"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
+<space:RegionTimeline id="heads" within={vertical} recipe={tracking.heads.default}/>
+<caption-fine:Track id="captions" document={story.caption}
+  timeline={speech.timeline} regions={heads}>
+  <caption-fine:Use style={caption-style}/>
+</caption-fine:Track>
+```
+
+The RegionTimeline's ids match Script Roles. Fine places a single-Role Cue at that region's top
+center; `anchor-x: center` and `anchor-y: bottom` put the Cue above it. The Style still owns its width,
+font and motion. Supplying `regions` requires every Cue on that Track to have one Script Role, even
+when that particular Role uses fixed placement. Author the relevant Role Cues in Script. The
+`@hypit/spatial` and `@hypit/caption-fine` READMEs own the exact data behavior.
+
+## 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.