@aswless_854771076/ai_short_studio_cli 0.1.98 → 0.1.100

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/production/audio-presentation.md

@@ -0,0 +1,49 @@
+# Place independent sound
+
+Read this when supplying music, ambience, narration or effects independently of placed Takes.
+[Sound](sound.md) presents audio already on the Timeline. If a narration performs the work's Script,
+prefer an audio-only SemanticTake and Sound so its words establish reusable semantic time.
+An independent audio contribution can still follow that same Script's events.
+
+## Prepare and place the source
+
+With the source, Clock, Script and Timeline already declared:
+
+```svml
+<import as="pipeline" from="@hypit/media-pipeline@1"/>
+<import as="audio" from="@hypit/audio-track@1"/>
+<pipeline:Normalize id="hit-media" source={hit-source} clock={clock}
+  video="none" audio="default" span-authority="audio"/>
+<audio:Track id="effects" timeline={program.timeline}>
+  <audio:Item id="reveal-hit" source={hit-media.media}
+    at={story.moment.reveal} for="600ms" playback="once"
+    gain="0.45" fade-in="0f" fade-out="3f"/>
+</audio:Track>
+```
+
+An Item consumes normalized audio-bearing media and a projected Window. Music can occupy a Segment
+or the program; effects can follow Moments. Shared [time forms](timing.md) also allow independent
+clock events. The Track publishes `.program` and `.audio`; select `.audio` in Film to hear it.
+An explicit Item id gives Studio a useful name. Two Items using one source remain two placements.
+
+## Choose source playback and mix
+
+`trim-start` and `trim-end` are source durations in frames, milliseconds or seconds; the end is
+exclusive. For example, `1s` to `3s` selects those two source seconds. This differs from Media Track's
+integer frame trim properties. Destination time remains the Item's Window.
+
+- `once` / `once-start` plays from the Window start; `once-end` aligns native playback to its end.
+- `loop` / `loop-start` and `loop-end` repeat with the selected alignment.
+- `stretch` retimes with pitch preserved and requires explicit `min-rate` and `max-rate` bounds.
+
+Playback expresses the intended occupancy. A long Window does not automatically loop or stretch
+a short source. The installed `@hypit/audio-track` README owns exact behavior and rate constraints.
+
+`gain` is a linear multiplier, defaulting to 1; fade durations default to `0f`. Normalization preserves
+source level. Overlapping Audio Items mix; overlapping visual Items instead compose by paint order.
+Balance music, speech, ambience and effects in the actual Film. [Sound direction](../playbooks/craft/sound-mix.md)
+owns the audible judgment, including ducking and continuity.
+
+A sound can share a semantic Moment with a reveal while remaining a separate contribution. If a
+visual component owns a coupled sound, it can publish a peer AudioTrack output; Film still selects
+that sound explicitly. Neither route requires reading another component's private state.

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/production/authoring.md

@@ -0,0 +1,228 @@
+# Authoring a production
+
+Read this when turning the current Treatment into Author Sources, Recipes, Runs, project components,
+and Builds, or when revising an existing production.
+
+[Script and semantic time](../creation/script-and-time.md) explains target wording, Segments, Roles,
+Caption Cue decisions and semantic relationships. [Script syntax](script-syntax.md) gives their exact
+forms; [Timing](timing.md) projects them into components. [Source syntax](source-syntax.md) explains
+imports and references.
+[Composing Tracks](tracks.md) connects the visual and audio roles; [Track authoring](track-authoring.md)
+and [Caption authoring](caption-authoring.md) explain creating a new project component for them.
+[Component design](component-design.md) explains shaping its behavior and controls around the work.
+[System relationships](system.md) connects these concepts to execution and Results;
+[media preparation](media.md) explains material inputs. [Production navigation](index.md) locates
+specialized questions without requiring every page for every revision.
+
+## Turn the Treatment into relationships
+
+Begin with the work the Treatment describes, not with a package inventory. Identify:
+
+- the meaningful, performable Script passages and any speaking roles;
+- the performances placed on Timeline and the independent material supplied to other components;
+- the picture and sound contributions the work needs, including a simple full-frame performance;
+- the semantic relations that should follow words, phrases, pauses, or content events;
+- the genuinely clock-based events;
+- the final Film or other deliverables.
+
+Bring the relevant directing knowledge into those decisions: use
+[Script and semantic time](../creation/script-and-time.md) for the verbal structure and the meanings
+other layers will follow,
+[image direction](../playbooks/craft/image-direction.md) for generated camera images,
+[video direction](../playbooks/craft/video-direction.md) for generated performance and action,
+[voice direction](../playbooks/craft/voice-direction.md) for casting and directing a character's voice,
+[voice and performance](../playbooks/craft/voice-and-performance.md) for A-roll and recurring voices,
+[B-roll](../playbooks/craft/b-roll.md) for coverage,
+[screen demonstrations](../playbooks/craft/screen-demonstrations.md) when an interface carries evidence or explanation,
+[Caption](../playbooks/craft/captions.md) for speech-linked text, and
+[graphic composition](../playbooks/craft/graphic-compositions.md) for designed visual hierarchy,
+with [motion graphics](../playbooks/craft/motion-graphics.md) for changes within it.
+These pages establish what the authored relationship should accomplish. Installed vocabulary then
+supplies the exact language for expressing it.
+
+For a performance-led work, including pure A-roll or short drama, prefer Script and semantic
+preparation even when the presentation is simple. Preserve the actual event relationships when
+additional Caption, sound or visual direction is introduced. A standalone asset edit can instead
+end at its requested media Output.
+
+Author those relationships explicitly. Script Selections and Moments carry meaning through placed
+performances into real time; authored positions locate independently timed events on the same Timeline.
+Track and Film elements arrange the resulting picture and sound. One Author entry connects the
+work; imported Sources and project modules divide its meaningful responsibilities. A camera cut
+is not by itself a reason for another Source, Segment, component or Build.
+
+When a role first leads to an installed Surface in the current work, query its actual declaration
+before writing the element:
+
+```bash
+hypit vocabulary @hypit/gpt-image --tag Image
+```
+
+Use the logical Module import, tag, attributes, children, ports, and output paths that this project's
+selected installation reports. Query again when the selected package or Distribution has changed, or
+when an error shows that the assumed declaration is no longer the installed one; an already
+established Surface does not need to be rediscovered for every edit. After writing one coherent
+Source or Run change, check that actual entry:
+
+```bash
+hypit check authors/main.svml
+```
+
+`vocabulary` establishes what the selected package declares. `check` resolves the real Source closure
+and verifies its imports, references, types, outputs, and Run choices. `plan` resolves the current
+Run's required capabilities; `hypit doctor` actively diagnoses the selected Profile and account
+reachability. Those are execution questions rather than additional authoring checks.
+
+When observation has already produced useful authored data—such as a per-frame region sequence for
+placing Caption above a moving head—keep that data in Source or Recipe and pass it through the
+component's declared input. It is part of the chosen production design, just like a Frame or Style.
+
+When the desired measurement depends on generated footage, the first Build supplies that footage.
+Observe it, author the resulting data, and reuse the produced media in the next composition Build.
+[Caption tracking](../playbooks/craft/caption-tracking.md) describes this loop for head placement.
+
+## Give each production surface one job
+
+- An **Author Source** (`.svml`) owns the target Script, media requests, components, Tracks, Film, and
+  public Outputs. It imports the vocabulary it uses and may import other Author or Recipe Sources.
+- A **Recipe Source** (`.svs`) owns reusable authored values such as a visual Style or request
+  configuration. It remains explicit input to the Source that uses it.
+- A **Run Source** (`.svrun`) binds one Author entry, names the public Outputs this execution requires,
+  and selects any file, earlier Result, or Fragment Candidates used for it.
+- A project **Author Package** under `packages/` owns a visual or semantic role that deserves its own
+  vocabulary and implementation.
+
+A project may have several of each. Different Runs against the same Author Source are useful when
+their demanded Outputs or Candidate selections genuinely differ. Repeating one Run creates another
+Build; it does not create another production.
+
+Use [Source syntax](source-syntax.md) for language forms and [Runs](runs.md) for execution choices.
+`hypit vocabulary <package>` or a focused tag or visual query supplies the installed Surface's
+attributes and outputs. Package-local documentation supplies its exact behavior and API. Source
+imports select author vocabulary; Runtime configuration selects external facilities.
+
+## Use Runs for execution choices
+
+A Target marks where this Run asks the graph to become real. For ordinary commissioned production,
+the demanded Output is usually the finished video, and the Build produces its required media
+dependencies through the same graph. A public image, Take, audio item, or other intermediate Output
+is also a normal Target when the user requested that deliverable or the work genuinely needs it
+independently now.
+
+Every public Author Output that completes while satisfying the demanded Target is stored in that
+Build Result and can be inspected or reused later. Derived public Outputs such as a SemanticTake
+therefore remain available when a downstream Target caused them to complete.
+
+The Author Graph supplies primary Candidates. A Run may explicitly select another compatible
+Candidate for a Logical Output:
+
+- `<file>` admits project media as a zero-input Candidate;
+- `<build-record>` names one public Output from one earlier Build Result;
+- a Run Fragment computes one or more Candidates from its explicit inputs;
+- `<satisfy>` selects one declared Candidate for one Logical Output.
+
+Candidate selection is an implementation decision for this Run. Core checks nominal Type
+compatibility and plans the combined Author and Run graphs. It replaces the displaced upstream
+subgraph while preserving any upstream Outputs that the selected Candidate itself consumes.
+
+[Runs](runs.md#generate-material-while-composing) shows how to target prepared material while
+component work continues, then reuse that material for focused rendering and delivery.
+
+## Reuse produced work explicitly
+
+For a revision or retry, continue using produced media that still serves the current intent. Preserve
+the Run's unrelated Candidate selections and add explicit selections for newly completed Outputs
+that the next Build should keep. Replacing one image or changing a Caption does not release every
+other output back to generation. Removing a `satisfy` restores that output's primary Candidate, which
+may submit a new paid request even when the Source and output name have not changed.
+
+The exact address of an earlier public Output is its Build id plus Output name:
+
+```svml
+<build-record id="opening-take"
+  build="bld_20260902T110000001Z_0000000001" output="opening-take.video"/>
+<satisfy output="opening-take.video" candidate="opening-take"/>
+```
+
+If the current Logical Output was renamed, the two names may differ: `build-record output` remains
+the old Result's public name, while `satisfy output` names the current graph position. Hypit does not
+infer that two names carry the same creative meaning.
+
+Use `hypit builds`, `hypit inspect <build-id>`, and `hypit history <output-name>` within the selected
+production's Result repository, following its recorded Builds and Runs to the needed Output. In a
+shared repository, the Source and Run establish which target an entry belongs to; an output name
+alone does not. Write that exact choice into the Run. Results retain public Outputs even when no file
+was exported into `assets/` or `output/`; inspect them before concluding that material is missing.
+A failed or cancelled Build may still contain completed public Outputs worth using. Reuse those
+Outputs rather than submitting their generation again to recover a later failure. A later Build
+that forwards an earlier Output does not copy its bytes. New structured Outputs also keep references
+to reused media inside them; wrapping a video in another value does not create another video file.
+
+A `<file>` Candidate refers to the selected file. Replacing that file changes subsequent reads;
+removing it leaves a missing dependency. A new Build records the selected reference without copying
+the file into every Result. A Candidate that generates new media saves its new output normally.
+
+The current Build's generated media normally continues downstream as the material for the commissioned
+work. Reusing it explicitly lets Caption, MG, Effects, composition, and final encoding change without
+submitting the same paid media requests again. The following examples locate the reuse boundary:
+
+| Current change | Keep through Candidates | Recompute or request |
+| --- | --- | --- |
+| Caption appearance, MG, an Effect or composition changes | Existing media and SemanticTakes whose Script identities and timing still apply | The changed visual systems and render |
+| Moment/Selection placement changes, with unchanged spoken tokens and Take identities | The accepted SemanticTakes and other material | Current Script references, their projections and presentation |
+| Cue grouping, word attributes or display-only Dual wording changes without changing speech tokens | The accepted SemanticTakes | The current CaptionDocument and its presentation |
+| Take placement or complete Timeline extent changes | The prepared local Takes | Timeline assembly, all affected projections and presentation |
+| Only some B-roll images must change | The existing performance, voice and all other still-useful media | The deliberately replaced images and their downstream composition |
+| The presenter changes while the spoken argument still fits | Unaffected B-roll, icons, music and other media that still serve the target | The new presenter images, affected performances, their normalization and semantic timing, and downstream composition |
+| A new product changes the demonstration or claims | Views and media whose content still fits the new Treatment | The affected product views, performance, Script-dependent timing and visual treatment |
+| The same video needs different normalization or semantic timing | Its generated video Output, or normalized media when that still applies | The affected normalization or alignment and downstream consumers |
+| New spoken wording requires a new performance | Unaffected Takes and other still-useful inputs | The changed performance and the timing derived from it |
+
+Choose an Output upstream of the work being changed, with the same nominal Type and the intended
+creative meaning. An unchanged SemanticTake can preserve both media and alignment. It is valid only
+while its Narrative, Segment, token and anchor identities and timing still describe the current
+Script and media. A Script edit does not automatically invalidate every Take; inspect what changed.
+Markers select existing token/Segment anchors. Moving a marker can therefore reuse accepted timing
+when those anchors and spoken tokens remain the same; no acoustic measurement is needed merely
+because a cue now follows another word. Changing spoken text, tokenization, Segment identity or the
+source performance requires a fresh judgment about the affected Take. Keep the media upstream when
+it still fits and let the required preparation recompute. No reuse selection automatically adapts an
+old Take to new speech.
+
+Do not satisfy a changed Track or final composition with its old rendered Output, which would hide
+the current edit. Type compatibility alone cannot establish that an old performance or timing still fits.
+
+After a person or product swap, review existing Candidate selections against the new target. A Run
+that still selects the old presenter's Take will keep that person on screen even after the image
+prompt changes. Preserve unrelated work while selecting or generating the media the adaptation needs.
+
+For example, correcting three wrong B-roll selections means replacing those selections while keeping
+the produced performance. Inspect the resulting plan: the new image requests may be intended; a new
+performance request is not explained by that correction. [Builds](builds.md) covers submission and
+inspection when an earlier attempt may still be running.
+
+## Revise the fact at its owner
+
+Before editing an existing production, establish the current facts that can affect the change. Read the
+relevant parts of its Brief and Treatment and the affected Source, Recipe or Run; inspect Results and
+Runtime activity when reuse or active execution matters. Read the relevant diff and preserve unrelated work.
+
+- Revise Treatment when the creative design changed.
+- Revise Script when words, Cue breaks, Selections, or Moments changed.
+- Revise Source or Recipe when composition, parameters, or authored timing relations changed.
+- Revise the Run when the demanded deliverable or selected Candidate changed.
+- Revise a project package when its fixed or reusable behavior needs to change; an unexposed local
+  design detail can be edited there without creating a new parameter.
+- Revise a media request when the desired shot or the user's requested media has changed.
+
+Generated Result bytes are evidence and reusable inputs, not editable Source. A change that still
+uses existing media should keep selecting it. A change that intentionally requests new paid media
+should first make the additional request visible in `hypit plan` and then follow the user's spending
+authority.
+
+## Use each view for what it can establish
+
+`hypit check` establishes Source and graph legality. `hypit plan <run>` shows the selected graph and
+external requests without submitting them. Studio opens that same Run for visual authoring.
+Only `hypit build <run>` submits work and creates a fresh Build Result. None of those facts alone says
+that the video is creatively successful; review the visible work as described in `review.md`.

package/skills/using-vvicat-ai-short-studio-cli/references/hypit/production/browser-capture.md

@@ -0,0 +1,112 @@
+# Capturing websites and authored HTML
+
+Read this when a page, product interface or locally authored HTML should become captured picture
+material. [Screen demonstrations](../playbooks/craft/screen-demonstrations.md) owns what the screen
+must show and why; this page owns how to save that material. `hypit capture` supplies browser
+capture from the installed Distribution; the project's scripts describe the actual page interactions.
+A captured image or recording enters the composition through Media, while an editable demonstration
+can use a project component. [Spatial layout](spatial.md) owns fitting either into its destination.
+
+## Save a page or region
+
+```bash
+hypit capture screenshot https://example.com/product \
+  --viewport 540x960 --scale 2 --full-page --to assets/product-page.png
+
+hypit capture screenshot https://example.com/product \
+  --selector '#comparison' --to assets/comparison.png
+
+hypit capture screenshot ./assets/card.html \
+  --viewport 1080x300 --transparent --to assets/card.png
+```
+
+Use `--clip x,y,width,height` for a rectangular region in CSS pixels. A selector, clip or full-page
+capture chooses a different extent; the default captures the viewport. Viewport and device scale
+are separate: 540 × 960 at scale 2 produces a 1080 × 1920 viewport image. They are task choices;
+Puppeteer's device emulation is available in a script when mobile behavior or a user agent matters.
+
+The command waits for page load. `--wait-for <selector>` waits for a visible element, and `--wait-ms`
+adds a chosen delay. If content loads through scrolling or interaction, express that in a script.
+Watch the saved image to see whether it contains the intended evidence and is readable in its
+destination Frame.
+
+## Use ordinary page interactions
+
+For several captures, lazy loading, an authenticated page or a demonstration, put the actual
+interactions in a project `.mjs` file. This script needs no Puppeteer import:
+
+```js
+// scripts/capture-product.mjs
+export const options = {
+  launch: { defaultViewport: { width: 1280, height: 720, deviceScaleFactor: 1 } },
+};
+
+export default async ({ page, screenshot, record, args, log }) => {
+  const [url, destination] = args;
+  await page.goto(url);
+  await page.waitForSelector('#comparison', { visible: true });
+  await screenshot({ path: 'assets/comparison.png', selector: '#comparison' });
+
+  log('Recording the product interaction');
+  const recording = await record({ path: destination, fps: 30 });
+  await page.click('#show-example');
+  await page.waitForSelector('#example-result', { visible: true });
+  await recording.stop();
+};
+```
+
+```bash
+hypit capture run scripts/capture-product.mjs -- \
+  https://example.com/product assets/product-demo.mp4
+```
+
+The selectors above describe an example page; choose the real controls and meaningful start and end
+states of the page being captured. Use normal Puppeteer navigation, locators, input and evaluation
+to express the task. `browser` is also available for opening more pages; pass one as the second
+argument to `screenshot` or `record` to capture it. Returning finishes open recordings and closes
+the browser. Completed captures survive a later script failure.
+
+For a scrolling demonstration, identify the container that actually scrolls; a gallery may move
+inside a fixed page. Record the intended interaction and compare separated saved frames to confirm
+that the page's rows or states actually change. Crop and presentation can then be revised around
+this recording without repeating the capture.
+
+For local inputs beside the script, `new URL('../assets/card.html', import.meta.url).href` locates
+the file. Relative output paths follow the directory where the command runs. `args` contains the
+arguments after `--`; use `log` for progress. `--json` reports every completed helper output with its
+path and actual dimensions, plus recorded duration and frame rate. Output paths must be new.
+
+## Browser and recording choices
+
+Use an installed compatible browser or prepare the package's tested browser once with
+`hypit capture install-browser`. Installation uses Puppeteer's browser cache and leaves existing
+browsers in place. [Network preparation](../environment/local-tools.md#make-network-preparation-practical)
+explains diagnosing a slow download. The package manifest owns the recommended version. For an explicit alternate selection, use
+`--browser-version <exact-version>` and `--browser-cache <directory>` on both preparation and capture.
+`install-browser --browser-download-base-url <url>` selects a compatible archive source for that
+installation only, with no source fallback. Capture never installs the missing browser.
+`--channel chrome` selects an installed Chrome;
+`--browser <executable>` selects another explicit compatible path. `--headed` opens a visible
+window. The script's `options.launch` accepts ordinary Puppeteer launch options, including a chosen
+`userDataDir` when a dedicated persistent browser profile is useful. CLI browser options override
+the script's choices. `--timeout-ms` sets page operation and navigation timeouts.
+
+Native page recordings require Chrome 153 or later, supplied by `install-browser`. They produce MP4;
+use an `.mp4` destination. `record({ path, audio: true })` includes page audio when the demonstration
+needs it; the default captures picture only. The browser performs encoding. `ffprobe` on `PATH`
+reads the saved file's actual dimensions and duration; `options.ffprobePath` can select another
+executable. `record` accepts Puppeteer's `RecordOptions`, including `fps` / `frameRate` as a maximum
+capture rate and `maxWidth` / `maxHeight` for output dimensions. Music, narration and effects added
+in the edit remain ordinary authored audio layers. The helper sets maximum dimensions from the
+viewport's device-pixel dimensions; Chrome determines the recorded size. Device scale can enlarge
+a screenshot without enlarging the recording. Use the saved video's reported dimensions when
+placing it in the composition.
+
+## Place the captured material
+
+Keep captures in project assets and record the source page and its purpose in the project notes.
+An image enters through `media:Image`; a recording enters through `media:Video` and the ordinary
+[normalization path](media.md). Place them with
+[Media presentation](media-presentation.md#keep-display-time-and-source-playback-distinct) and the Script's
+Selections or Moments as appropriate. Their visibility, crop, scroll and transitions belong to the
+composition, so those changes can reuse the captured file.