@aswless_854771076/ai_short_studio_cli 0.1.98 → 0.1.100

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/playbooks/craft/shot-production-contracts.md

@@ -0,0 +1,161 @@
+# Shot production contracts
+
+Read this when creating `ASSETS.md` and `SHOTS.md` for reference-led recreation or a generated
+multi-shot narrative. These are project notes, not a second state machine. Keep only fields that carry
+a real decision, reference edge or review obligation.
+
+## Record selected assets in `ASSETS.md`
+
+Give every continuity-bearing asset a stable key and version. A selected board is usable only after
+original-resolution review.
+
+```markdown
+## character:lead / appearance:v1
+- canonical facts: face, hair, body proportions, grooming and makeup
+- costume signature: clothing, shoes, accessories
+- performance anchors: posture, gait, habitual gaze or gesture
+- selected board: productions/<target>/assets/lead-v1.png
+- provenance: generated from <references>; reviewed <date>
+- forbidden drift: alternate face, hairstyle, costume or body type
+
+## scene:kitchen / version:v1
+- geometry: entrances, exits, fixed architecture and camera sides
+- anchors: foreground, midground and background objects
+- light: motivated source, direction, quality and color
+- selected board: productions/<target>/assets/kitchen-v1.png
+
+## prop:cup / state:full
+- form: scale, material, color and markings
+- ownership: lead character, right hand after contact
+- selected board: productions/<target>/assets/cup-full.png
+```
+
+Use the installed `@hypit/gpt-image-kits/asset-sheet` Prompt Kit to prepare character, scene or prop
+boards. A changed costume, damaged object, different contents or changed time-of-day is another version,
+not an informal prompt variation.
+
+## Make every `SHOTS.md` entry executable
+
+One entry owns one atomic production unit. Use human-readable prose; the headings below are a contract,
+not a requirement to serialize the document as JSON.
+
+Begin `SHOTS.md` with a semantic event table. Script words, actions and state changes own timing; seconds
+and frames are reproducible compilation evidence. When a selected audiovisual result, accepted speech
+timing or upstream shot duration changes, recompile every dependent event before generating or editing.
+
+```markdown
+## Semantic event timeline
+
+| event id | semantic anchor | source evidence | depends on | fps | target frame/time | observed frame/time | delta/status |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| male-face-reveal | after the woman's final word and settled reaction | reference 00:23.600 | S11 | 30 | 708 / 23.600 s | pending selected Film | pending; pass at ≤1 frame |
+```
+
+```markdown
+## shot:S03
+- source evidence: reference 00:08.200–00:10.000; transcript words or observed action
+- narrative job: what changes and why the shot exists
+- generated duration / intended edit: 5 s / 2.3 s
+- provider / model / mode: StarRouter / Seedance / ReferenceVideo
+- picture-and-sound: joint native audio
+- first readable state: people, positions, gaze, held objects and prop states
+- causal action: onset → path → contact/change → response/recovery
+- stable tail: final positions, pose, gaze, held objects and remaining motion
+- camera: side, axis, framing, lens character and one movement curve
+- light and look: source, direction, exposure, white balance, texture and diffusion
+- exact dialogue: one row per turn with speaker, original text, detected/confirmed language code,
+  confidence, measured delivery and whether the speaker is visible
+- sound: voice identity, ambience, action sounds and room perspective
+- risk storyboard, when needed: reason, selected path, cell count and review status
+- depth: `generate | reuse`; Provider, workflow/model, source shot, expected local Output,
+  selected Result or reuse candidate and review status
+- audio reference: selected path, language/voice/emotion responsibility and review status
+- video prompt: selected Text Output/version and review status
+- continuity in/out: previous shot relation, screen direction, entry/exit edge and intended cut
+- timing: semantic event/word anchors, target compiled frames, observed selected-Result frames, delta/status,
+  generated duration and intended edit
+- approved visible text: exact text, storyboard path, panel/state order, format, geometry, visual review and
+  prompt timing; `none` when absent
+- selected audiovisual Result/version: current generated picture-and-sound source
+- identity review: `required | approved | rejected | not_applicable`; list every required character,
+  selected character-board version when present or required-board identity evidence, reviewer, evidence
+  frames and decision
+- native audio / speech timing / Caption timing / lip-sync review: selected versions and review status
+- candidate budget: ordinary shots default to 2; named high-risk shots may use up to 3 when approved
+- attempt ledger: candidate, observed failure cause, changed variable and decision
+- same-cause failure count / next fallback: stop paid retries at 2 and return to storyboard, reference
+  selection, continuity or model choice
+- generation status: blocked | ready | submitted | accepted | rejected
+- review risks: identity, hands/contact, text, audio, transition or other shot-specific risks
+```
+
+`generated duration` is the Provider request length. `intended edit` is the expected retained portion.
+Do not hide the difference by shrinking dialogue or action to an implausible speed.
+
+For recreation preprocessing, the selected Runtime must route subtitle removal through StarRouter
+`comfly/1194` and depth generation through StarRouter `comfly/1776`, one source shot and one expected
+local Output per workflow. Review the subtitle-removed picture against the source before using it as
+the depth input. The source shot may feed only this preprocessing edge when the Brief forbids source
+picture and audio in the remake.
+
+The selected generated audiovisual Result is the authority for its performed timing. Selecting or
+regenerating a speaking shot invalidates every older word alignment, Caption timing and lip-sync review
+derived from that shot. Return it and dependent edit events to `blocked`, then transcribe/review and
+recompile from the new selected audio. Source audio may support analysis but must not enter a complete
+remake's Timeline.
+
+## Bind the ordered reference manifest
+
+Append one row for every actual generation reference. Order and model labels must match the submitted
+Surface children exactly. This table is a StarRouter Seedance example; another Endpoint may use a
+different prompt-label dialect.
+
+```markdown
+| order | model label | role | selected file/version | responsibility | person reference | measured duration |
+| --- | --- | --- | --- | --- | --- | --- |
+| 1 | @图片1 | character-identity | lead-v1.png | face, body, costume | true | — |
+| 2 | @图片2 | scene | kitchen-v1.png | geometry, materials, light | false | — |
+| 3 | @视频1 | depth | S03-depth.mp4 | structure, motion and camera | false | 5.0 s |
+| 4 | @音频1 | audio-reference, if required | S03-reference.wav | voice, delivery, emotion and room | false | 4.8 s |
+```
+
+Use H3 Ref2VA labels instead of Seedance labels for H3. Preserve the actual input order in every H3
+section. One reference has one primary responsibility even when it supplies useful supporting detail.
+A remote task id or URL is provenance, not the selected local asset.
+
+## Apply the generation gate
+
+Mark a shot `ready` only when:
+
+- every selected asset board exists and passed review;
+- every visible key character has an `approved` identity review against a selected character board;
+  `required` or `rejected` blocks Timeline admission and requires regenerating that shot;
+- any risk storyboard required by the plan is connected and reviewed;
+- its depth video and reviewed video prompt are connected, with an audio reference when required;
+- start and tail states agree with adjacent accepted shots;
+- manifest labels, order, files and Provider metadata match the actual Surface;
+- joint native audio is enabled for every final shot, including wordless ambience and action, unless an
+  explicit silent-video requirement or Endpoint limitation is recorded as a waiver;
+- visible dialogue fits the duration and names the correct speaker;
+- every source dialogue turn has its own confirmed language code and the prompt repeats that code beside
+  the exact line, including when adjacent turns use different languages;
+- approved visible text is exact, while incidental subtitles, glyphs, logos and watermarks are banned;
+- source picture and source audio are absent when the Brief requires a complete remake.
+
+For an exact countdown or device state, create a temporal storyboard—six cells by default—with each
+required reading or state isolated in its own cell. Approve the original-resolution cells, then
+pass the board as a semantic image reference to the video model and state the exact sequence and timing
+in the prompt. The output must be one normal full-frame video, never the visible grid. Dialogue subtitles
+remain a separate downstream Caption concern.
+
+Stop after two candidates fail for the same observed cause. Do not buy another draw with equivalent
+inputs: change the owning storyboard, reference binding, continuity contract or model, record the new
+decision and obtain approval for any additional candidate budget.
+
+Never repair a rejected generated shot by painting, inpainting, compositing, replacing a local region or
+splicing source pixels into it. Correct the prompt and references, then regenerate the smallest failing
+shot and run the same review again.
+
+After generation, update the entry with the actual Result and acceptance decision. If a reference or an
+accepted previous tail changes, return the dependent shot to `blocked` until its manifest and continuity
+state are reviewed again.

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/playbooks/craft/sound-mix.md

@@ -0,0 +1,76 @@
+# Sound and mix
+
+Read this when deciding what the audience should hear across a passage or the complete Film, and
+how the work's existing sound relates to added music or effects. [Voice and performance](voice-and-performance.md)
+owns who performs the words and where that voice comes from.
+
+## Start with the sound the material already carries
+
+In speaking-video A-roll, the person's picture, words and voice belong to the same performed Take.
+Its sound continues at the current Timeline position while B-roll, graphics or a different view
+changes the picture. Audio-only A-roll likewise supplies performed speech, with its picture authored
+separately. A wordless performance may carry its own sound or be silent. Present the selected Take's
+audio through [Sound](../../production/sound.md) according to what this passage should actually play.
+
+B-roll can be a still, a silent video, or video with useful source sound. Its visual role alone does
+not decide whether the audience hears that sound. A lifestyle shot might contribute a particular
+door, footstep or burst of laughter; a picture covering a presenter's explanation may contribute no
+audio at all. [Media](../../production/media-presentation.md#include-sound-deliberately) makes source
+audio an explicit choice, leaving the selected performance voice available beneath a silent picture.
+
+Listen to what the chosen material already contributes before adding sound. Music can carry pace,
+mood or a change of thought; a short effect can give contact, reveal or transition an audible edge.
+A sustained environmental sound can locate a place or connect cuts when the material itself does not.
+These describe jobs in the work, not separate layers to fill. Environment may already be audible in
+the performance; its duration alone does not make it a different kind of asset from an effect.
+Designed quiet can be just as expressive as an added sound.
+
+Hypit provides ways to prepare, place and mix audio, not a maintained stock collection of BGM,
+short effects or long environmental sounds. Choose or make the particular material the work calls
+for from supplied, recorded, generated or otherwise available sources and project Outputs. Treatment
+captures why it belongs; Source and the chosen components express its use.
+
+## Shape what leads the ear
+
+When speech carries the idea, let the important words be readily understood in the finished mix.
+Music and effects can yield around a name, number, claim, punchline or quiet reaction, then take
+more space in a pause or a passage led by action or music. Set that relationship through level,
+placement, fades, arrangement and the selected source, rather than assuming every moment needs the
+same balance. Normalization prepares a source; the audible balance is decided in the composition.
+
+Give each added sound an expressive reason. A comparison can share a motif; a reveal may earn one
+precise accent. A tactile process may be better carried by its small contact sounds than by a large
+impact. Repeating an effect because another cut occurred can exhaust its meaning; variation is useful
+when the event's dramatic role changes. Let the piece's character guide the palette.
+
+## Attach sound to the event it answers
+
+A sound responding to spoken meaning can follow a Script Selection or Moment, so it moves with the
+accepted performance. A sound belonging to a component's own entrance, state change or handoff can
+follow that event within the component. Music or another independently directed event can occupy
+an authored span of the Film. Choose the time relationship from what makes the sound happen; the
+same visual and audible event can share a cause without being forced into separate timing schemes.
+
+The owner follows that relationship. [Sound](../../production/sound.md) presents audio from placed
+Takes; [Audio Track](../../production/audio-presentation.md) places independent audio; Media or a
+project component can publish sound coupled to its own picture and events. Film includes the wanted
+audio contributions explicitly. These are composition choices, while the installed packages own
+their exact playback, trigger and gain syntax.
+
+## Preserve continuity across picture changes
+
+A picture cut need not cut the acoustic world. Room tone can continue across views of one place,
+music can bind a montage, and a speaking Take can remain audible as another picture takes the frame.
+A change of place, speaker perspective or narrative state may instead call for an audible handoff
+even when the picture changes gently. Follow the listener's sense of the encounter.
+
+Let speech, source action and effect tails meet in the rhythm the scene needs. Use silence, fades or
+overlaps where they make that handoff audible. Review the actual Film where these sounds coexist:
+the chosen voice remains clear when it carries meaning, an effect belongs to its event, and the
+soundtrack retains the work's intended character across the passage.
+
+For a multi-shot recreation, define one scene-level acoustic baseline before generating or mixing:
+room tone, perspective, reverb, noise floor and music state. Treat generated breaths, footsteps and
+contact sounds as shot material to audit, not automatically compatible ambience. Carry the baseline
+under adjoining cuts, crossfade perspective changes, and replace contradictory generated sound instead
+of accepting a new acoustic world at every shot.