Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
docs(skill): clarify production choices and adaptive composition
kashorin6c23bc19ff49
diff --git a/packages/media/README.md b/packages/media/README.mdindex 04e42065..0bc48c1e 100644--- a/packages/media/README.md+++ b/packages/media/README.md@@ -17,3 +17,21 @@ The same module owns the deliberately narrow `SynchronizedMedia` contract used anormalization. It contains one common `frameRate`/`frameCount`, an optional visual Artifact with itsintrinsic pixel extent, and an optional audio Artifact. Source stream indexes, selection authority,normalization ledgers and repeated codec/rate constants are not downstream media fields.++## Font files++`Font` takes an explicit source path and the selected face's real weight and style:++```svml+<media:Font id="caption-font" src="./assets/fonts/creator-bold.otf" weight="700" style="normal"/>+```++The source can be a project font, a user-supplied file, or an installed font's file path. The Host+stages its bytes as an ordinary resource; the render machine does not need that font installed.+Project-relative assets make the Source portable. The supported filename extensions are `.ttf`,+`.otf`, `.woff` and `.woff2`. The Surface has no selector for a face within a `.ttc`/`.otc` collection;+use the intended standalone face. Weight/style metadata describes that face, not a synthetic transform.++Caption Fine and Typography Styles can consume this value as their primary `font` or an explicit+Fallback face. `@hypit/fonts-open` offers bundled faces through the same media types; its catalog+does not limit which external fonts an author may supply.diff --git a/packages/provider-whisperx-local/README.md b/packages/provider-whisperx-local/README.mdindex c7cbed3a..6e6fc64e 100644--- a/packages/provider-whisperx-local/README.md+++ b/packages/provider-whisperx-local/README.md@@ -33,3 +33,12 @@ This prevents a warm process with an incompatible inference configuration from aThe Runtime installs and starts the packaged service in the machine Program Home when this Endpointis selected. The environment is reused across projects and sessions. The current local package andservice are trusted code; this is not a community-plugin sandbox.++`hypit paths` reports the machine `hostState`. The managed installation lives below+`<hostState>/programs/whisperx-<encoded Endpoint instance>-<encoded service host>/`, with Python in+`.venv/` and the service's NLTK data in `nltk_data/`. Both identifiers use `encodeURIComponent`;+the service host includes its port. The default service is `http://127.0.0.1:8765` and exposes+its configuration through `/health`. Inspect an existing Profile's address and expected settings+when locating that service. A custom `serviceCommand` supplies its own installation and start command.+`hypit programs status` checks the Programs selected by the supplied Profile; `programs up` prepares+and starts them. The managed installation does not require a global `whisperx` shell command.diff --git a/skills/hypit/SKILL.md b/skills/hypit/SKILL.mdindex b56dbb83..2e779db5 100644--- a/skills/hypit/SKILL.md+++ b/skills/hypit/SKILL.md@@ -5,12 +5,16 @@ description: Make, adapt, and revise videos with Hypit from references or briefs# Hypit-You are the director and producer entrusted with delivering the user's video. Look at the material-they give you, understand the intention behind their request, and develop a creative answer you can-stand behind. Watch the reference, inspect its frames, and read the words in time. Image, video, and-audio models produce your directed material; Author Packages express the composition; the Runtime-runs the production. Discover why the work holds attention, and make the-aesthetic and technical choices that bring the new piece to life.+You are the director and producer entrusted with making the video the user is asking for. Understand+their request and supplied material, and develop a creative answer you can stand behind. Keep the+intended result clear in Brief as the work develops; let it guide what you create, adapt and reuse.+Watch the reference, inspect its frames, and read the words in time. Discover why the work holds+attention, and make the aesthetic and technical choices that bring the new piece to life.++Take responsibility for creative and technical execution. Bring the user into meaningful choices+about their goal, private facts, connecting services, substantial machine preparation and spending.+Carry their settled choices into the work and project notes. Image, video and audio models produce+your directed material; Author Packages express the composition; the Runtime runs the production.Bring the sensibility the video calls for: quick internet wit, warmth, social intuition, restraint,or playful absurdity. Let it shape your ideas, images, words, and performances. Through every style,@@ -18,10 +22,10 @@ remain grounded, curious, imaginative, and discerning. Be perceptive about the whonest about the details, and curious when something does not yet make sense. Look for connectionsthat explain an unexpected choice. Draw on the relevant Skill references and keep what you learnin the project files as you go. Speak in the user's language, with warmth and specifics from the-work. Keep them involved as the video takes shape: share discoveries, meaningful creative choices,-and progress toward the result. When setup, generation or rendering takes time, explain what is-running or what is holding up the work. These updates accompany continued work within the user's-commission; ask for a reply when a decision needs their input or authority.+work. Share what you have understood, the choices shaping the piece and progress toward delivery.+When setup, generation or rendering takes time, explain what is running or what is holding up the+work. A question should make the user's actual choice clear; a progress update keeps them involved+as you carry out the commission.Most work Hypit is asked to clone is creator-led, phone-captured short-form UGC: spoken expression iscarried by one or more A-roll performances while B-roll, Caption and MG reshape what the viewer sees.@@ -38,9 +42,11 @@ in the piece itself. Carry that intention into the material requests.Prefer to author the video's meaning in Script and let the accepted performance give it time.In a clone, discover what a cut, picture, reveal or sound responds to, then recreate that relationship-for the target's words and intention. Selections can carry an explanation or comparison; Moments can-carry an answer or payoff. This is Hypit's strong production prior. Use explicit clock timing where-the work calls for it, and use named wordless Segments when action or silence carries the passage.+for the target's words and intention. Selections carry explanations or comparisons; Moments carry+answers or payoffs. This is Hypit's strong production prior: a new wording or delivery moves the+presentation with its meaning. Preserve what each event responds to. In an authored animation,+give messages, reveals and state changes their own reading rhythm. Durations shape how events+unfold; semantic anchors locate events that belong to speech. A piece can use both relationships.Before writing or adapting an image prompt, read[Image direction](references/playbooks/craft/image-direction.md) and apply it to the intended picture,@@ -64,11 +70,13 @@ crafts explain resolution and duration choices.## Prepare for the work at hand-Use the [Runtime Profile](references/environment/profile.md) to establish word alignment for spoken-work and the generation, processing and rendering that the production needs. Inspect the existing-setup and carry working choices forward. Explain the capabilities this piece will need, then resolve-the choices that matter to the work at hand, using the actual account, local and hosted options.-Watching supplied material and developing its interpretation can proceed while setup is being resolved.+For a spoken reference, use WhisperX's transcript and word times to connect speech with picture+changes. It can run through a local or hosted Endpoint. Check the relevant existing setup and local+preparation. Use+[environment selection](references/environment/profile.md#choose-the-practical-capability-path-with-the-user)+to explain the practical options, including HypiHub, and the effort, accounts and costs involved.+Prepare the path the user chooses. Reference interpretation and component work can progress alongside+the environment and generation work they do not depend on.## Understand and direct@@ -99,8 +107,8 @@ within the agreed commission. Develop components, Recipes and semantic arrangemeruns. Plan shared framing needs in Treatment and direction; judge the actual overlap of pictures andgraphics once the production media is available.-Build around the directed material and existing Outputs. Use the Script and established semantic-timing to locate the passage being composed. Watch how MG, Caption, B-roll, Typography+Build around the directed material and existing Outputs. Locate the passage through its authored+events; for spoken work, use Script and the established semantic timing. Watch how MG, Caption, B-roll, Typographyand Effects work together in Studio or rendered Results: the graphics make the idea clear,the Caption is easy to read, and the pictures and effects appear where and when they serve thepassage. Adjust the owning Source or component to improve those relationships. Reuse produced media@@ -109,9 +117,12 @@ lets B-roll cover the explanation it supports. The composition is ready when itscarry the Treatment clearly and compellingly. Reconsider Treatment when the design itself needs tochange; change Brief when the user's goal changes.-Choose component boundaries through shared behavior. Reuse Media for ordinary presentation; let a-video viewport and graphics share one component when they move or arrange together. Independent-Caption and overlays can remain peers. [Component design](references/production/component-design.md)+Give useful relationships clear names and leave their expression to the component. Choose component+boundaries through shared behavior. Reuse Media for ordinary presentation; let a+video viewport and graphics share one component when they move or arrange together. Reuse Fine+Caption for flowing speech text, or author a Caption family for a new relationship among words and+graphics, carrying the same Script wording and semantic timing. Independent contributions can+remain peers. [Component design](references/production/component-design.md)explains how semantic events make these compositions reusable.Create project components as normal production work. Use the most representative available media@@ -122,19 +133,18 @@ practical, revisit that choice and carry the improvement into the work and its n## Standing responsibilities-- **Money.** Before paid work, establish the billing accounts, what work is covered, and the- expected cost or budget the user accepts. Account setup establishes access; spending follows the- user's agreement to the work and cost. Proceed under existing authorization that covers the work,- including transcription, generation and processing when they are part of that commission.- Explain progress and costs as it advances. Seek a new decision for work or cost outside that- agreement, or an account outside it. Preserve the agreement in Brief;+- **Money.** Before paid work, establish the billing accounts, covered work and expected cost or+ budget the user accepts. Preserve that agreement in Brief and apply it across the commission's+ covered transcription, generation and processing. Changes beyond its work, cost or accounts need+ the user's decision. Account setup establishes access; the agreement establishes spending authority.[Builds](references/production/builds.md#work-within-the-agreed-paid-scope) explains estimates,early transcription and how authorization applies to execution.-- **Existing work.** When revising or retrying, preserve usable produced media through explicit Run- Candidates and retain unrelated selections. Inspect project Results, including useful Outputs from- failed Builds; an absent exported file does not mean the Output was never produced. A new Build- does not automatically reuse an earlier one. Before submission, check that `plan` contains only- the new media requests the current work actually needs. Correct accidental generation before spending.+- **Existing work.** Judge earlier material against the current Brief and Treatment. Preserve+ Outputs that still serve the production through explicit Run Candidates, retaining unrelated+ selections while completing the requested changes. Project Results can contain useful Outputs+ even from failed Builds. Check `plan` for the intended remaining requests; reuse across Builds+ requires an explicit selection. [Authoring](references/production/authoring.md#reuse-produced-work-explicitly)+ explains choosing the Output that preserves material while allowing the current edit.- **Execution.** A Build is one execution attempt. When a watching terminal closes or times out,Runtime status establishes whether that Build is still running; stopping `--follow` only detachesthe observer. After execution fails, preserve available Outputs in a new Run and submit a new Build.@@ -149,13 +159,9 @@ practical, revisit that choice and carry the improvement into the work and its nKeep the whole-piece reading in Analysis, its timed realization and meaning in Timeline, the user'sgoal in Brief, and your creative answer in Treatment. Progress carries the current question, whatremains to examine, and the next useful action. Keep these files current enough for another- conversation to continue the work. Resume by reading them with the relevant Skill references,- Sources, Runs, project Results and Runtime status. Continue using produced work already available.+ conversation to continue the work. Resume from the current request and these notes, with the+ relevant Skill references, Sources, Runs, project Results and Runtime status.The project-files reference below owns document responsibilities and the suggested layout.-- **Who decides.** The user owns the goal, private facts, real value choices, and spending. You own- casting, art direction, shots, performance, Caption, components, prompts, and implementation. Ask- when a decision requires user authority that the Brief, references, existing preferences, or- spending approval do not provide. Otherwise decide and continue.- **Project ownership.** Preserve unrelated Source, Recipe, Run, assets, and project-package work.Make production changes at their owning source; keep Result media intact. New reusable behaviorbelongs in a project component, without patching the installed Distribution for one video.@@ -174,7 +180,7 @@ practical, revisit that choice and carry the improvement into the work and its n| locating an existing `hypit` installation, or installing or updating the executable after Skill setup | `references/environment/distribution.md` || what this machine can do, credentials, Model/Provider/Endpoint choices or shared capacity | `references/environment/profile.md` || a new model, another service or Key for an existing model, or a project Model/Provider extension | `references/environment/model-and-provider.md` |-| a local binary, WhisperX, or a Managed Program that will not come up | `references/environment/local-tools.md` |+| assessing local WhisperX preparation, installing local tools, or repairing a Managed Program | `references/environment/local-tools.md` || understanding a reference video or link | `references/creation/reference-video.md` || defining the target: what the user asked for, and what the new piece will be | `references/creation/brief.md` || cloning with supplied faces or products, changing the Script, language, length, or combining references | `references/creation/transformations.md` |@@ -185,7 +191,8 @@ practical, revisit that choice and carry the improvement into the work and its n| directing generated video, visible performance, silent action, camera behavior, cuts or request duration | `references/playbooks/craft/video-direction.md` || deciding who is A-roll, recurring voice identity, covered performance or independent narration | `references/playbooks/craft/voice-and-performance.md` || designing B-roll coverage, montage, short display windows or editorial handoffs | `references/playbooks/craft/b-roll.md` |-| designing Caption reading rhythm, styling, placement or a new Caption family | `references/playbooks/craft/captions.md` |+| grouping Chinese, English or mixed-script Caption, reading rhythm, styling or placement | `references/playbooks/craft/captions.md` |+| applying Caption Styles by speaker or passage, overriding a treatment, or hiding selected captions | `references/production/caption-program.md` || designing MG, a board, cards, graphic state, hierarchy, palette or reveals | `references/playbooks/craft/graphic-compositions.md` || deciding which generated images or videos should depend on which references | `references/playbooks/craft/generated-dependencies.md` || directing music, sound effects, ambience, gain, ducking or the completed mix | `references/playbooks/craft/sound-mix.md` |@@ -194,11 +201,12 @@ practical, revisit that choice and carry the improvement into the work and its n| choosing an existing Prompt Kit, assembling its wording or authoring a new one | `references/production/prompt-kits.md` || Run syntax, material Targets, Candidates, Run Fragments or reusing produced media | `references/production/runs.md` || admitting media, normalization, SemanticTakes, still clips, trims or extraction | `references/production/media.md` |+| downloading a reference or source video from a link with yt-dlp | `references/production/video-downloads.md` || capturing a website, recording a page interaction or exporting a local HTML graphic | `references/production/browser-capture.md` || composing, correcting, resizing, cropping or cutting out an image | `references/production/image-operations.md` || faces, MG, Caption, insets or layered screens must share one frame, or a subject's background needs removing | `references/playbooks/craft/compositing.md` || Canvas, Frames, aspect, fitting, cropping or coordinate relationships | `references/production/spatial.md` |-| font resources, multilingual text, Emoji, titles or rich Typography | `references/production/fonts-and-text.md` |+| choosing or finding fonts, using local font files, multilingual text, Emoji or Typography | `references/production/fonts-and-text.md` || which installed Surface to use, or whether to write a project component | `references/production/vocabulary.md` || sharing a component, Prompt Kit, Model, or Provider across projects | `references/production/component-sharing.md` || the A-roll semantic timeline and composing Media, Audio, Caption, Text, MG and Effect Tracks | `references/production/tracks.md` |@@ -208,7 +216,7 @@ practical, revisit that choice and carry the improvement into the work and its n| writing a Caption family with new word relationships, scheduling or layout | `references/production/caption-authoring.md` || `plan`, Provider pricing information, `build`, a retry or interrupted submission, following work, Results and exports | `references/production/builds.md` || opening Studio, understanding its views and edits, or adding a component Companion | `references/production/studio.md` |-| Film assembly, picture and sound, final rendering or a selected frame interval | `references/production/rendering.md` |+| Film assembly, pure MG with authored time, picture and sound, final rendering or a selected frame interval | `references/production/rendering.md` || judging the preview or finished Result and deciding what to fix | `references/production/review.md` || recognizing a whole-work format, combining formats, or discovering another directing Craft | `references/playbooks/index.md` |diff --git a/skills/hypit/references/creation/brief.md b/skills/hypit/references/creation/brief.mdindex 4cd7a56e..1c66513a 100644--- a/skills/hypit/references/creation/brief.md+++ b/skills/hypit/references/creation/brief.md@@ -36,6 +36,8 @@ by non-secret labels or Endpoint references, the work they cover, and the acceptbudget. Retain any limits the user attached to that agreement. Distinguish your proposed estimatefrom what the user has accepted, and an estimate from a firm spending ceiling. Keep the agreementcurrent when the user changes it so another conversation can continue under the same authority.+Record their local or hosted setup choices and accepted preparation in the same ordinary language.+The Runtime Profile expresses how to execute those choices; Brief preserves what the user agreed to.[Builds](../production/builds.md#work-within-the-agreed-paid-scope) owns how it applies to paid work.## Treatment is the director's answerdiff --git a/skills/hypit/references/creation/project-files.md b/skills/hypit/references/creation/project-files.mdindex 48e0fc3e..e6968525 100644--- a/skills/hypit/references/creation/project-files.md+++ b/skills/hypit/references/creation/project-files.md@@ -6,6 +6,15 @@ names.## Establish the project boundary+Understand the current request and keep its intended result in [Brief](brief.md). Locate the work+through the user's supplied paths, the current project and its notes, following linked assets or+shared libraries where their relationship to this production is clear.++Judge earlier work by what it contributes to that target: a reference, a component, or material that+still fits the intended person, product, words and presentation. Explain what can be carried forward+and what the requested changes require. A proposal to deliver a different existing video changes+the commission and belongs in the conversation with the user.+Run commands from the video project's root. A small `package.json` makes that root explicit andcan later hold the project's component dependencies:diff --git a/skills/hypit/references/creation/reference-video.md b/skills/hypit/references/creation/reference-video.mdindex ed2420ea..d80dabc4 100644--- a/skills/hypit/references/creation/reference-video.md+++ b/skills/hypit/references/creation/reference-video.md@@ -4,6 +4,9 @@ Read this when a video or link is evidence for what the new work should preservefrom. The useful result is a timecode-level semantic reading: what the piece communicates, and howits exact audiovisual choices make that communication work.+For a reference supplied as a link, [video download](../production/video-downloads.md) explains+`hypit media fetch`, its local preparation and the saved source file used by the tools below.+## Read the whole through its detailsWatch the whole reference from opening to close. Follow its hook, argument or story, shifts of@@ -45,6 +48,9 @@ reveals and emphasis. Keep that transcript beside the reference and interpret itsurrounding argument, visible names and supplied context. Small transcription errors can coexistwith a clear understanding of what the passage means.+[Environment selection](../environment/profile.md#choose-the-practical-capability-path-with-the-user)+explains assessing local preparation and choosing the local or hosted path for this transcription.+WhisperX's recognized spelling reflects the recognizer's interpretation of the audio. Coined wordsand unfamiliar names are especially prone to substitutions, so a spelling difference alone cannotestablish a pronunciation error. The transcript helps recover the reference's content and locatediff --git a/skills/hypit/references/creation/script-and-time.md b/skills/hypit/references/creation/script-and-time.mdindex 8273ad48..60d5dd2c 100644--- a/skills/hypit/references/creation/script-and-time.md+++ b/skills/hypit/references/creation/script-and-time.md@@ -99,6 +99,9 @@ word it belongs with and does not create another speech time unit. CJK prose comone Han, Hiragana or Katakana character per lexical unit; compounds, decimal numbers and the spokenside of Dual Text preserve their own lexical structure. This is why Cue breaks, word attributes andsemantic markers attach to complete authored units instead of punctuation or visual line positions.+Character-level timing does not call for character-sized Cues: use `||` for meaningful reading+phrases. [Caption craft](../playbooks/craft/captions.md#language-changes-the-reading-unit) explains+Chinese, English and mixed-script grouping, spacing and their fit in the picture.## Write the intended pronunciation@@ -174,7 +177,7 @@ Script also represents passages without speech:No words does not mean no semantics: the Segment retains its identity and start/end anchors. Itsassociated normalized media determines the duration, and its SemanticTake has an empty word array.The same SemanticTrack and Track timing vocabulary apply to a wordless passage or an entire-speech-free piece. The empty tag itself declares neither a zero-length interval nor a duration.+piece made from prepared media. The empty tag itself declares neither a zero-length interval nor a duration.Choose Segment boundaries from natural production passages and delivery length, not from everypicture cut. One Segment and Take can carry several speaking turns, camera cuts or a split-screen@@ -182,6 +185,27 @@ conversation. One continuous narration can carry many B-roll changes through Selcan deliberately use several Takes driven by the same character-and-scene image; a natural cut isoften part of its appeal. A Role change or `||` does not require another generation.+## 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 event timing together in the owning component's Source.+An event can have an identity such as `question` or `reveal` and an authored `at="2.6s"` without+inventing spoken words or a media-backed Segment. Film time is declared through ProgramSpace;+[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. A projected expression such as `instant="moment.cue + 12f"` with+`moment={story.moment.intro}` keeps an interval relative to that spoken event. The event's trigger+and its entrance duration are different choices:+`at={story.moment.answer}` locates the answer; ten frames can give its arrival a particular character.+## Measure before choosing durationsFor a new or revised A-roll performance, choose time from the target's words, delivery, and action.@@ -272,6 +296,7 @@ A Window occupies an interval:| `during={story.segment.hook}` | The Segment's Window. || `during={story.selection.proof}` | The Selection's Window, including its authored affinities. || `at={story.moment.claim} for="8f"` | A Window beginning at a Moment and lasting eight frames. |+| `at="2s" for="12f"` | A Window beginning two seconds into the film and lasting twelve frames. || `until={story.moment.claim} for="250ms"` | A 250 ms Window ending at a Moment. || `start="program.start" end="moment.cue" moment={story.moment.claim}` | A Window composed from two explicit endpoints. |@@ -286,9 +311,15 @@ An Instant names one point:| Form | Result || --- | --- || `at={story.moment.claim}` | The authored Moment. |+| `at="2s"` or `at="12f"` | A point on the film clock, in seconds or frames. || `at={story.selection.proof} boundary="start"` | The Selection's chosen boundary. || `at={story.segment.hook} boundary="end"` | The Segment's chosen boundary. || `instant="program.start + 8f"` | An explicit clock expression. |+| `instant="moment.cue + 12f" moment={story.moment.claim}` | Twelve frames after the Moment, following it when the delivery changes. |++`at="12f"` locates an event; `for="12f"` gives an interval its length. Frames use the selected+film clock. Semantic projection keeps the event's Script identity alongside its resolved frame,+so its authored relationship remains available for later changes.A particular Surface may deliberately expose only some of these forms. Its vocabulary reports theattributes it actually accepts; the shared spelling does not grant every component every temporaldiff --git a/skills/hypit/references/environment/local-tools.md b/skills/hypit/references/environment/local-tools.mdindex 0ba82a2c..52448068 100644--- a/skills/hypit/references/environment/local-tools.md+++ b/skills/hypit/references/environment/local-tools.md@@ -1,7 +1,19 @@# Local tools and Managed Programs-Read this when the selected Profile uses local media, HyperFrames, WhisperX, OpenCV, or another local-Endpoint and its executable or Managed Program is unavailable.+Read this when assessing local preparation, selecting local WhisperX, or preparing and repairing a+local Endpoint's executable or Managed Program.++## Assess local preparation++Use `hypit paths` to locate the selected Profile and machine state. Inspect relevant service+configuration, the Provider's documented installation locations, and executables such as `ffmpeg`+and `uv`. Hypit's managed WhisperX has its own Python environment; a missing global `whisperx`+command leaves that installation's state unknown. The installed `@hypit/provider-whisperx-local`+README owns its preparation and service locations.++Establish what already works, what needs starting or repair, and what needs downloads. Use those+findings in [environment selection](profile.md#choose-the-practical-capability-path-with-the-user),+then prepare the chosen setup using its Provider instructions and the evidence from its logs.## Diagnose the selected local capabilitydiff --git a/skills/hypit/references/environment/profile.md b/skills/hypit/references/environment/profile.mdindex d63f67ec..7da901fc 100644--- a/skills/hypit/references/environment/profile.md+++ b/skills/hypit/references/environment/profile.md@@ -23,6 +23,62 @@ and editing does not acquire an image model merely because another production usalignment establishes speech timing, and authored generation Needs require their selectedproduction capabilities. Local media inspection prepares reference frames and clips independently.+## Choose the practical capability path with the user++Read the project's relevant choices and inspect its tools, Profile, credentials and local preparation.+Keep a working setup the user has chosen. For a spoken reference, transcription may be the immediate+need while image and video requests are still taking shape. Explain the capabilities the piece will+need, and make the setup choice concrete through what is available, the preparation effort and cost.++`programs status` and `doctor` describe the selected Profile. A Profile containing only hosted+alignment leaves local WhisperX readiness unexamined. [Local tools](local-tools.md#assess-local-preparation)+explains where to inspect existing preparation and known service configuration.++- Recommend local WhisperX when the machine and preparation time make it practical. Its calls have+ no hosted Provider charge; first preparation may install a runtime and download model weights.+ [Local tools](local-tools.md#select-local-whisperx-explicitly) owns setup and repair guidance.+- Use a supported BYOK Provider when the user already has that account and wants to use it.+- Offer HypiHub when the user prefers one hosted account or wants an alternative to local preparation.+ It hosts WhisperX and supported image, video and audio models, so the same account can serve+ reference understanding and later generation. Check access for the capabilities this work needs.++When the path is undecided, share those findings, recommend a practical choice and ask which setup+suits the user. Their decision can cover the preparation as a whole. Record it in+[Brief](../creation/brief.md#brief-preserves-user-authority); the Profile implements that choice.+[Paid scope](../production/builds.md#work-within-the-agreed-paid-scope) explains how the commission+covers service charges. Prepare further model credentials as the creative plan needs them.++Switching from BYOK or local execution to HypiHub changes the selected service and may change the+billing account. That remains a user choice when the earlier route encounters authentication, quota,+rate-limit or service errors. An OAuth page follows the decision to connect the selected account.++## Create a Profile when the project needs one++From the project directory:++```bash+hypit runtime init+hypit paths+```++`runtime init` writes and selects an editable starter `hypit.runtime.json`. It preserves an existing+Profile and performs no installation or login. Use `hypit runtime use <profile>` to select an+intentional existing Profile for this project.++The official video Distribution's starter includes:++- `hypihub.default` for remote generation and WhisperX alignment;+- `media.local` for local media processing;+- `hyperframes.local` for local visual rendering.++These entries describe initial routing. Adapt them to the local and hosted services the user has+chosen. A missing credential on a starter entry describes that entry's readiness. The user's choice+is recorded in Brief; the actual setup may use BYOK, local WhisperX or another supported deployment.+Each authored model needs an Endpoint that supports its exact requested capability.++Runtime selection is project-local. Commands read that project's `.hypit/runtime` pointer and do not+choose a Profile from a familiar filename or from another project above it.+## Keep the owners separate| Owner | What it decides |@@ -126,68 +182,6 @@ Read the installed `@hypit/runtime-local` README for the shared model and the seaccepted settings. Use `hypit activity` to inspect actual claims. After changing a Profile, follow[Worker reload guidance](../production/builds.md#reload-changed-execution-code-deliberately).-## Begin with the Distribution starter--From the project directory:--```bash-hypit runtime init-hypit paths-```--`runtime init` writes and selects an editable starter `hypit.runtime.json`. It does not install a-package, contact a service, request a credential, or start a Worker, and it preserves an existing-Profile. Use `hypit runtime use <profile>` to select an intentional existing Profile for this project.--The current official video Distribution starts with:--- `hypihub.default` for remote generation and WhisperX alignment;-- `media.local` for local media processing;-- `hyperframes.local` for local visual rendering.--This is a useful first configuration, not an Author-language rule. A project may select BYOK-Providers, local WhisperX, remote rendering, or another supported deployment without changing its-Source. Exact models remain author choices and are demanded only when the selected Run reaches them.--Runtime selection is project-local. Commands read that project's `.hypit/runtime` pointer and do not-choose a Profile from a familiar filename or from another project above it.--## Choose the practical capability path with the user--Inspect the available tools, selected Profile, configured credentials and relevant Endpoint diagnoses-before asking the user to set up anything. Keep working choices and explain which ones this piece-will use. For a typical generated reconstruction, consider reference transcription, image generation-and video generation together, giving the user a clear picture of the capabilities the work needs.--Resolve the choices needed for the current work. For a spoken reference, word timing may be the-immediate need while the specific image and video requests are still taking shape. Explain the local-and hosted paths and their consequences for later production; ask about existing accounts when that-helps choose a path. Prepare further credentials when the creative plan needs those services.-Revisit a choice when the user's intention or available environment materially changes.--- Use a supported BYOK Provider when the user already has that account and wants to use it.-- For speech alignment, offer local WhisperX when the machine and the user's available setup time- make it practical. Its calls have no hosted Provider charge; first preparation may install a- runtime and download model weights. [Local tools](local-tools.md#select-local-whisperx-explicitly)- owns setup and repair guidance.-- Offer HypiHub as the official hosted option when the user prefers one hosted account or does not- have the corresponding BYOK or local capability. It hosts WhisperX and supported image, video and- audio models, so the same account can serve reference understanding and later generation. Check- the selected account's access and available quota for the capabilities the work needs.-- Image, video, voice, and audio production each require an actual selected Endpoint for the exact- authored model. Check support for the capabilities this work actually requests.--HypiHub is a convenient selected Provider, not an automatic fallback. Moving from BYOK or local-execution to HypiHub changes the Profile or its binding explicitly; an authentication error, exhausted-quota, rate limit or service failure never authorizes that switch or a different billing account.-Ask for a user decision only when the alternatives have a meaningful consequence,-not merely because several equivalent implementations exist.--Explain a setup choice in terms of the work it enables, its preparation effort and which account-would pay. [Paid scope](../production/builds.md#work-within-the-agreed-paid-scope) connects that choice-to the user's commission. Continue independent work, such as watching reference frames or studying-the supplied product, while a needed setup decision is being resolved.-## Put secrets behind credential referencesA Profile names a Credential Store and key; the secret stays in that store. The writable OS store@@ -200,14 +194,15 @@ Inspect one Endpoint's credential slots without revealing their values:hypit auth status hypihub.default```-When the Endpoint declares an acquisition flow or the selected store accepts interactive input, use:+Once the user has chosen to connect that account, use its declared acquisition flow or the selected+store's interactive input:```bashhypit auth login hypihub.default```-OAuth may open the Provider's browser flow. Another Endpoint may securely prompt for its exact secret-or accept `--from <secret-file>`. An Endpoint backed by the read-only environment store is configured+For an OAuth Endpoint, this command opens the Provider's browser flow immediately. Another Endpoint+may securely prompt for its exact secret or accept `--from <secret-file>`. An Endpoint backed by the read-only environment store is configuredin the Worker process environment instead.Keep secrets out of Author Sources, Runs, Runtime Profile JSON, project documentation, commanddiff --git a/skills/hypit/references/playbooks/craft/captions.md b/skills/hypit/references/playbooks/craft/captions.mdindex 8215aff8..e5db8eee 100644--- a/skills/hypit/references/playbooks/craft/captions.md+++ b/skills/hypit/references/playbooks/craft/captions.md@@ -12,8 +12,22 @@ Independent titles, lower thirds, labels and editorial paraphrases belong to theFor implementation of a new visual family, read[Caption authoring](../../production/caption-authoring.md). That guide keeps the common text/timingchain and shows where the new family owns scheduling and rendering.+For choosing Chinese, Latin or mixed-script faces, using a local font or finding a new one, read+[Fonts and text](../../production/fonts-and-text.md).-## One data contract, three presentation layers+## Direct captions for this video++Use the reference to understand what its captions contribute: how they group speech, emphasize an+idea, establish a speaker or fit around the picture. Carry those relationships into the new work+when they serve its Brief. A new language, performer, product or tone can call for a different face,+grouping, placement or motion. Direct that treatment from the new Script's meaning and the video's+vibe, and record the choice in Treatment and its Recipe.++A short handoff can land a punchline; a longer phrase can let an explanation breathe. Both are useful+when the viewer can read the thought and follow the picture. The reference, language and intended+energy inform that judgment rather than prescribing a fixed Cue length or one caption look.++## Caption families, Styles and parametersScript publishes one `CaptionDocument`: ordered display words, complete Alignment Units, speakingRoles, word attributes and authored Cue handoffs. Caption joins it to the real SemanticTrack. That@@ -23,7 +37,7 @@ and measured speech evidence.Direct the presentation through three related layers:-| Layer | What it decides |+| Choice | What it decides || --- | --- || **Family** | The structural visual language and scheduling behavior the Caption can express: uniform flowing words, independently arranged phrases, speaker-attached shapes, or another authored relationship. || **Recipe and resolved Style** | One coherent treatment within that family. An SVS Recipe gathers a useful combination; the family's Style Surface resolves it with fonts or other explicit resources. Role or Selection applications can choose among those Styles. |@@ -35,6 +49,10 @@ project `.svs`; a set that has earned reuse across works can become an ordinaryunder its owner's scope. Such a collection preserves the family, Recipe and intended use togetherrather than turning isolated parameter values into universal defaults.+Caption Program chooses where those Styles apply: a default, a speaking Role, a semantic passage or+a local emphasis. [Caption styling and coverage](../../production/caption-program.md) explains+overrides, Segment-wide selections, word attributes and hiding selected captions with Mute.+## Keep wording and timing in their ownersScript owns display words, speaking Roles, Dual Text units, attributes and `||` Cue Breaks. Its@@ -46,7 +64,7 @@ Use the produced performance's normalized and aligned audio. A change to that auits cuts can change word timing and requires corresponding alignment. A visual-only restyle canreuse the same semantic and media outputs through the Run.-## Start with the Fine family's real expressive range+## Reuse Fine or author a new familyUGC, podcast and interview work can use `@hypit/caption-fine`. Fine supports exact fonts,placement and anchors, wrapping, Cue boxes, active-word treatment, lead/tail and motion through@@ -67,12 +85,18 @@ Use the owning package README and `hypit vocabulary @hypit/caption-fine` for curKeep one coherent interpretation of the Script across speakers and styles; different colors do notrequire unrelated transcripts or separately invented timing.-Fine's uniform-flow layout is a particular family and a useful broad implementation. When the work-needs new structural relationships within a Cue, create a project Caption family consuming the common-Caption data and semantic timing. Word attributes and semantic Selections can carry the authored roles-that family interprets; its own schedule and renderer can give those roles distinct arrangement and-animation. A new layout is normal component authorship. [Caption authoring](../../production/caption-authoring.md)-explains the boundary.+Fine is to Caption what Media is to ordinary picture presentation: a broadly useful reusable+component. A new visual relationship can become a project component directly. A Caption family can+arrange a phrase around its keyword, place speakers' phrases in a shared composition, or coordinate+words and graphics as one visual event. Word attributes and Selections carry the authored meaning;+the family owns how that meaning appears and moves. This is ordinary video authorship, including for+a treatment used in only one work.++Apply the same freedom to component boundaries. Independently behaving captions can remain a peer+Track. Words and graphics whose layout or motion belongs together can share a component, consuming+the common Caption document and semantic timing. Caption names the relationship between displayed+speech and its performance; it does not prescribe a separate visual layer or the Fine renderer.+[Caption authoring](../../production/caption-authoring.md) explains building that family or scene.## Design Cue rhythm with the Caption system@@ -87,12 +111,25 @@ depends on each other, and give a payoff or contrast its own handoff when the vithat separation useful. Keep a name, negation, article and noun, preposition and object, phrasal verb,or quantity and unit together when separating them would make either screen state harder to read.-For the compact Fine treatments common in short-form UGC, begin with two to four displayed words per-Cue, or an equivalently brief reading unit in writing systems that do not separate words with spaces.-Count what Caption displays: the spoken side of Dual Text does not make the visual block longer. This-range is a strong drafting prior for a quickly handed-off, animated Caption; the actual language,-delivery, font, width, motion and Canvas decide the finished grouping. Let a tightly bound phrase run-longer when its meaning would suffer from another handoff.+### Language changes the reading unit++English commonly uses a word as its smallest timed display unit; Chinese uses individual Han+characters. That gives Chinese precise character highlighting, while a Cue still holds a meaningful+phrase. A Chinese Cue can comfortably contain more characters than an English Cue contains words.+Choose its length from meaning, reading time and the space the actual font occupies. A fixed word+or character count cannot make that choice. Count the display side of Dual Text when judging fit.++| Writing | Grouping and presentation |+| --- | --- |+| English | Keep a useful phrase together, including its articles, negation and name or quantity. Word lengths vary, so the chosen face and width matter more than a word count. |+| Chinese | Keep compounds, names, modifiers and their objects together. Let a complete short clause share a Cue when it fits; repeated tiny character groups fragment both meaning and the screen. |+| Mixed Chinese and English | Read the phrase as a whole. A Latin brand name or number can occupy several Han characters' width; its lexical unit count does not predict that width. |++Fine already leaves adjacent Han characters together without English word gaps. Its `word-gap`+controls spaced boundaries, including Chinese/Latin transitions; `letter-spacing` adjusts tracking.+The same timing supports a stable complete Cue, current-character color or a trail. For flowing+Chinese speech, a readable phrase with restrained emphasis often works better than a separate bounce+or reveal on every character. Choose the response for the performance's energy.With Fine's uniform-flow family, direct the common Cue to remain on one line by considering itsgrouping together with the Recipe's font size, usable width and word gap. A stable line lets each@@ -101,22 +138,30 @@ reading position. A Caption family designed around a two-line stack, an oversizesupporting phrase, or another internal composition owns that relationship itself; its intentionalline structure is not a reason to add another `||`.-For example, a compact Fine treatment can begin with this phrase rhythm:+For example, these groupings preserve short ideas in each language:```svml<explanation><HOST>- One reference || can rebuild ||+ One reference can rebuild ||the shots and pacing, ||the captions and effects, ||around your product.</explanation>++<explanation-zh><HOST>+ 一张参考图 || 就能重新设计镜头和节奏,||+ 让字幕和特效 || 为你的产品服务。+</explanation-zh>```-Its Cues contain two, two, four, four and three displayed words, while articles remain with their-nouns and each list pair stays intact. The same sentence can justify another grouping when a-different family makes a contrast, keyword or reaction the visual event. The sentence supplies-semantic structure; the chosen presentation says how much of that structure should share one screen-state.+These are alternative Script excerpts, not a bilingual performance. Another width or delivery can+justify a different handoff. The sentence supplies semantic structure; the presentation says how+much of that structure should share one screen state.++Fine's optional `max-words-per-line` inserts visual line breaks by display-unit count. In Chinese,+that count is usually characters. Leave it unset for ordinary width-based flow; choose it when a+deliberate counted row serves the design. `max-lines` checks those counted rows and requires that+setting; it does not make a long Cue fit one physical line. The package README owns these controls.Use Studio or a rendered interval to see the Cue with actual speech. Repeatedly flashing tiny groupsusually means the viewer is being asked to reacquire text too often; an overfull block usually means@@ -129,6 +174,11 @@ Choose font, size, width, line height, contrast and motion together. If a Cue ovits authored grouping and its actual Style; do not assume every overflow has the same cause. Lead,tail and handoff shape visibility while karaoke follows semantic word timing.+Judge weight and outline from the actual glyphs. Dense Han characters need their internal spaces to+stay open; a heavy Latin-caption outline can overwhelm them. A clear face with a modest outline or+compact shadow can separate speech from a busy picture while preserving the letterforms. Changing+the language calls for reconsidering the treatment, not merely replacing the text in an English Recipe.+Treat Caption, icons, flashes and other graphics as a composition. A guest color and answer accentscan work together without coloring every system identically. Check readability acrosslight and dark frames, avoid hiding the important face or product, and allow enough space above adiff --git a/skills/hypit/references/production/caption-authoring.md b/skills/hypit/references/production/caption-authoring.mdindex 71ee92a6..7cda1aa7 100644--- a/skills/hypit/references/production/caption-authoring.md+++ b/skills/hypit/references/production/caption-authoring.md@@ -2,6 +2,7 @@Read this when a work needs a new relationship among its spoken words, layout and motion.[Caption craft](../playbooks/craft/captions.md) owns readability and directing judgment;+[Caption styling and coverage](caption-program.md) owns applying Styles and Mutes;[Track authoring](track-authoring.md) owns project package wiring.[Fonts and text](fonts-and-text.md) explains exact font resources and fallbacks;[component visuals](component-visuals.md) explains the final drawing representation.@@ -14,12 +15,33 @@ Fine Caption already covers uniform flowing text with exact fonts, Paint, boxes,placement and motion. Different colors, Role styles, cue entrances or head tracking may only requireSource and Recipe changes. A keyword occupying a separate oversized line, words playing differentvisual roles, or a recurring spatial relationship among speakers can justify a new family directly.-Creating that family is normal video production.+Creating that family is normal video production. Name the family for the visual relationship it+makes reusable, and name each Style for a particular treatment within it. A project can also own a+single-use caption composition when that is what the video needs.The result is still Caption when the displayed words correspond to speech and remain close to itsdelivery. Independent slogans, summaries and titles usually belong to Typography even if they reactto a Script Moment.+## Own the visual relationship++Media can present ordinary footage; a scene component can coordinate footage with diagrams or other+graphics. Fine and custom Caption families have the same relationship. Their shared input is the+authored speech and its semantic timing; the implementation owns the spatial structure and motion.++Start from what the viewer should understand or feel. A supporting phrase might establish the+thought while its key word takes the emphasis. Design how they enter, share space, respond to speech+and hand off to the next thought. That relationship suggests useful controls: the word's authored+role, fonts, relative sizes, placement and motion. Put the work's choices in its Style/Recipe and+the reusable arrangement in the renderer.++The output remains an ordinary VisualTrack. Its Presents can own trees of text, boxes, images and+other visual elements. When words and graphics share layout or motion, they can live in the same+component. [Component visuals](component-visuals.md#compose-video-and-graphics-in-one-browser-program)+also describes HTML/CSS browser programs with typed media and text children. That drawing freedom+applies to captions too: give the program the resolved caption schedule and explicit resources,+and evaluate its state at the requested frame. Keep separately useful overlays as peers.+## Keep the existing text and timing chain```text@@ -69,6 +91,12 @@ is a separate operation. A narrow width should not silently rewrite the Script iIf the family needs an additional grouping rule, give that rule explicit parameters and preserve theoriginal word/unit associations in the schedule.+Display Words follow the Script's writing system: a Han character is normally one Word, while an+English word is normally one Word. Keep that timing granularity separate from a phrase's visual+grouping. Compose adjacent Han characters without Latin word gaps, preserve punctuation with its+word, and use the selected fonts' actual widths for layout. Exercise mixed-script names as well as+plain English when the family will carry Chinese copy.+`caption:Mute` suppresses selected display units while preserving speech. A new family should usethe common mute application when scheduling, as Fine does. Validate that schedule, document, narrativeand ProgramSpace belong together; do not silently accept timing from another video.@@ -81,7 +109,8 @@ timeline and Caption Program; its Fragment performs the common timing join and irender operations. Register the new family's Producers and any new schedule Type in its own package.The renderer owns typography, structural relationships, stacking and motion. Use the existing text-shaping and Visual IR facilities; do not depend on an arbitrary system font or browser layout state.+shaping and Visual IR facilities with explicit font resources, including selected local font files,+so the same faces reach the rendering machine.Read `@hypit/caption-fine`'s `fragment.ts`, `schedule.ts` and `render.ts` as separate implementationexamples. Reuse the common parts and replace the actual family behavior, including its parametervalidation; renaming Fine while retaining its uniform-word assumption will not implement a structuraldiff --git a/skills/hypit/references/production/caption-program.md b/skills/hypit/references/production/caption-program.mdnew file mode 100644index 00000000..f5a47201--- /dev/null+++ b/skills/hypit/references/production/caption-program.md@@ -0,0 +1,93 @@+# Caption styling and coverage++Read this to apply a caption treatment to speakers or passages, change it locally, or leave selected+words without captions. [Caption craft](../playbooks/craft/captions.md) owns the visual direction;+[Caption authoring](caption-authoring.md) explains creating a new rendering family.++The Script owns displayed words and Cue breaks. A family's Style owns a resolved visual treatment.+`caption:Program` assigns those Styles to the words, then the family's Track joins them to the actual+SemanticTrack and draws them. Changing the appearance can reuse the existing performance and timing.++## Choose the words that receive a treatment++| Intended scope | Authoring |+| --- | --- |+| Ordinary treatment across the video | Set the Program's `default` Style. |+| A speaking character, across their turns and Segments | `Use role="GUEST" style={guest-style}` selects the Script Role. |+| A phrase, one Segment or a passage spanning several Segments | Name a Script Selection around that material and use `Use selection={story.selection.name} style={...}`. |+| A display word with a particular visual role | Mark a Script attribute and use `Use attribute="emphasis" style={...}` with a family that implements word-specific layout. |+| Selected words that should have no caption | `Mute role="GUEST"` or `Mute selection={story.selection.name}`. Speech and the semantic timeline continue. |++A Selection can cover a whole Segment; the Program consumes that Selection rather than a separate+`segment` selector. A Role selects the authored speaker, regardless of which person is currently+visible. For one speaker's particular reply, place a Selection around that reply. Each `Use` selects+one of `role`, `selection` or `attribute`; each `Mute` selects one of `role` or `selection`.++## Apply broad choices and local overrides++The following excerpt assumes the named Styles are already declared in the chosen family:++```svml+<script id="story">+ @opening-look+ <opening>+ <HOST> One simple idea.+ <GUEST> @answer It changes the whole picture. @/answer+ </opening>+ @/opening-look++ <demonstration>+ <HOST> @clear-picture Let me show you how it works. @/clear-picture+ </demonstration>+ <closing><HOST> Try it with your product.</closing>+</script>++<caption:Program id="caption-program" document={story.caption} narrative={story}+ default={base-style}>+ <caption:Use role="GUEST" style={guest-style}/>+ <caption:Use selection={story.selection.opening-look} style={opening-style}/>+ <caption:Use selection={story.selection.answer} style={answer-style}/>+ <caption:Mute selection={story.selection.clear-picture}/>+</caption:Program>+```++Role and Selection applications are evaluated in Source order. **The last matching `Use` wins** for+each complete display unit. In this example, the opening treatment replaces the guest treatment in+the opening passage, then the answer treatment replaces it in the selected reply. The closing keeps+the default. This gives the author an explicit order for broad treatments and particular moments;+selector specificity or proximity does not choose the winner.++Each match chooses a complete Style. To make an answer differ only in color, declare an answer Style+with the intended complete treatment; Program does not merge its properties with the previous Style.+The resulting Style boundaries form Cue handoffs, alongside Segment, Role-turn and authored `||`+boundaries. A selection-wide Style change is useful when a phrase becomes its own caption state.++`Use attribute="emphasis"` has a different purpose: it describes local word roles within a Cue for a+family that can arrange them. Fine keeps a uniform flow and does not implement word-specific Style+runs. An oversized keyword beside supporting words belongs naturally to a custom family consuming+those runs. Conflicting Styles applied to the same attributed word produce an error; the common+word-attribute mechanism does not use the Role/Selection override rule.++## Let coverage serve the composition++Mute is a display selection, useful when another visual already carries the words, a demonstration+needs the space, or another Caption family presents that passage. All Mute selections contribute to+the hidden words; a later Style application does not make them visible again. It changes neither+audio routing nor the performance. For a different version of the video, revise the Program's Mutes.++The family's lead, tail and handoff still determine the visible envelope of neighboring Cues. When+a passage needs a clear picture, select complete Cues and choose their neighboring lead/tail so the+previous or following caption also releases that space. Selecting a word for Mute removes that word;+it does not by itself make every caption pixel disappear during the word's time.++One family can implement several related treatments through its own Styles. When independent+families are useful in one video, give each its own Program and Track, with complementary coverage.+The common Program assigns Styles; it does not dispatch them to renderers automatically. A scene+whose words and graphics share behavior can instead own their rendering together through the common+Caption timing inputs, as described in [Caption authoring](caption-authoring.md).++Use semantic boundaries for the relationship: a Selection follows the intended words after a Script+or performance change. Keep a Dual Text unit complete when selecting it. Fine's moving placement+can independently follow measured head regions through [Caption tracking](../playbooks/craft/caption-tracking.md).+Inspect the resulting handoffs and placement with the other visuals while reusing the production's+media.diff --git a/skills/hypit/references/production/component-design.md b/skills/hypit/references/production/component-design.mdindex ff442ad1..362660c6 100644--- a/skills/hypit/references/production/component-design.md+++ b/skills/hypit/references/production/component-design.md@@ -25,6 +25,15 @@ A-roll names the performance carrying semantic time; it does not reserve the picTrack. Ordinary presentation can reuse Media; a new relationship can be authored directly. Aone-off scene is a useful component too. Caption and independent overlays can remain separate.+Choose visual grouping and timing independently. A combined scene can respond to spoken Moments;+separate Tracks can share an authored event. What belongs together on the canvas does not decide+what gives that behavior its time.++Fine Caption similarly offers reusable flowing text, while a custom Caption family can own a new+relationship among words and graphics. Both consume Script wording and semantic timing. Shared+behavior can keep these visuals together; [Caption authoring](caption-authoring.md) explains the+specialized text inputs and the same freedom to compose.+Give a reusable scene the prepared performance, its outer Window and the Moment that changes itslayout. Replacing a product or rewriting the Script then changes content and semantic anchors whilepreserving the behavior. The final frame positions come from the selected Takes.@@ -40,6 +49,12 @@ Prefer Script Selections, Moments and Segments for events that respond to the arThe Surface projects them through the accepted SemanticTrack; the component consumes the resultingWindows or Instants. A different delivery can then move the event while preserving its purpose.Explicit time remains useful for an authored lead, a short entrance or another clock-based decision.+In a pure MG piece, name the events that carry its meaning and direct their reading rhythm. A useful+component accepts resolved Instants or Windows so the same reveal can follow a Script Moment or an+authored time. Keep message content and its trigger together in Source; repeated children can each+have their own trigger. Use semantic examples first for speech-led roles, showing how a new performance+preserves the relationship. [Authored animation](rendering.md#compose-an-authored-animation) covers+the film clock when there is no performance.Choose the temporal input from what the component does. A picture covering an explanation occupiesits Selection. An answer revealed on a word can remain visible after that word ends. A ranking item@@ -70,7 +85,7 @@ that belong together. Palette, spacing and motion defaults should already form aSupport the variation the work actually needs. Longer names, another product, a different number ofrows or a changed performance may be ordinary inputs; a new visual relationship may deserve anothercomponent. Reuse becomes valuable when the next author can change the content while retaining the-idea. [Caption craft](../playbooks/craft/captions.md#one-data-contract-three-presentation-layers) gives+idea. [Caption craft](../playbooks/craft/captions.md#caption-families-styles-and-parameters) givesa concrete example of this distinction through family, Recipe/Style and parameters.## Design the component in its framediff --git a/skills/hypit/references/production/component-visuals.md b/skills/hypit/references/production/component-visuals.mdindex d5edd7ec..4420c0e7 100644--- a/skills/hypit/references/production/component-visuals.md+++ b/skills/hypit/references/production/component-visuals.md@@ -30,6 +30,11 @@ Use several Presents when items have separate lifetimes or stacking positions. Acan keep its settled rows visible while later rows enter. Its domain program decides those spansand states; the drawing output makes them explicit.+Track grouping is an authoring boundary; each Present has its own paint order among the film's+appearances. Its element tree supplies local layout and compositing scope. Use that tree or a browser+program for content that moves, clips or changes layout together. The final DOM follows these owned+visual relationships rather than the nesting of tags in Source.+## A working drawing function[visuals.ts](examples/visuals.ts) contains `renderCard`, a complete pure drawing function using@@ -92,6 +97,12 @@ owns the local structure; CSS supplies layout, stacking, masks, filters and blen`setup(root, data)` code returns `render(localFrame)`. This function sets the complete state at thatframe. A range render may start in the middle, so compute state from the frame and authored inputs.+For shared opacity or a filter, put the affected content under the element that owns the treatment.+A translucent panel can use backdrop filtering; its painted position and browser compositing scope+determine which background it affects. A transition can own both participating pictures and their+handoff. Choose the scope from the visible relationship, keeping independently useful contributions+as peer Presents. These are ordinary composition choices within the same rendering path.+Use ordinary typed children for prepared video, images and exact-font text. A `{{child-id}}` slot inthe HTML places each direct child exactly once. These children retain their declared resources,video sampling and font handling while participating in the program's HTML layout. Extra artifactsdiff --git a/skills/hypit/references/production/fonts-and-text.md b/skills/hypit/references/production/fonts-and-text.mdindex 4597b15a..40ab89f3 100644--- a/skills/hypit/references/production/fonts-and-text.md+++ b/skills/hypit/references/production/fonts-and-text.md@@ -1,7 +1,8 @@# Fonts and independent text-Read this when choosing exact fonts, handling multiple writing systems or Emoji, or placing titles-and labels. [Caption](../playbooks/craft/captions.md) covers text displayed with speech.+Read this when choosing or finding fonts, using a local font file, handling multiple writing systems+or Emoji, or placing titles and labels. [Caption](../playbooks/craft/captions.md) covers text displayed+with speech and the reading rhythm of Chinese and English Cues.The font's glyph shapes and spacing determine how text wraps and how much room it needs. A fontresource supplies those glyphs, a Style supplies their size and treatment, and a text item supplies@@ -23,15 +24,59 @@ then a color Emoji face. Choose fallback faces for the actual writing systems inWeight and style must exist in the chosen family. `hypit vocabulary @hypit/fonts-open` and thatpackage's README describe the installed catalog and supported combinations.-Font bytes are explicit production resources, so rendering uses the selected faces regardless of-the machine's installed fonts. A supplied brand font can be declared with its exact face metadata:+For Chinese-led speech, start with a face made for the intended script: the installed catalog+includes `noto-sans-sc` and `noto-serif-sc` for Simplified Chinese, `noto-sans-tc` and `noto-serif-tc`+for Traditional Chinese, and display faces such as `zcool-kuaile`. Choose their character to suit the+piece. A compact, clear face is useful for running speech; an expressive display face can suit a+playful caption or a short title. Inspect the real words at delivery size, including punctuation,+numbers and any Latin names.++Fallback order also directs the design. Inter first with Noto Sans SC after it gives Latin letters+Inter's shapes and Chinese Noto's. A Chinese face first can supply both scripts for a more unified+line. Similar numeric weights in different families can look different, so judge the pairing in the+same Cue. The renderer uses the exact supplied faces and disables synthetic bold and italic.++## Use fonts already on the machine or supplied by the user++Installed fonts are useful source material. Select their actual files and declare them as assets,+so the chosen face travels with the build instead of depending on a family name existing on another+machine. For example, a project can use a local brand face alongside an explicit Chinese fallback:```svml<import as="asset" from="@hypit/media@1"/>-<asset:Font id="brand-font" src="./assets/brand-semibold.woff2" weight="600" style="normal"/>+<asset:Font id="brand-font" src="./assets/fonts/brand-semibold.woff2" weight="600" style="normal"/>+<fonts:Face id="chinese-font" family="noto-sans-sc" weight="600" style="normal"/>++<caption-fine:Style id="caption-style" recipe={look.caption.primary} font={brand-font}>+ <caption-fine:Fallback font={chinese-font}/>+</caption-fine:Style>```-Pass `{brand-font}` to the receiving Style. The file and metadata describe the actual supplied face.+This excerpt assumes the `fonts`, `caption-fine` and Recipe imports. `asset:Font` accepts a file path;+copying a selected face into the project's `assets/fonts/` makes the Source portable. Use the file's+real weight and style. Declaring weight 700 does not turn a regular-only file into a bold face.++Useful places to locate fonts include Font Book and `~/Library/Fonts` or `/Library/Fonts` on macOS;+Windows Fonts and `%WINDIR%\Fonts` or `%LOCALAPPDATA%\Microsoft\Windows\Fonts` on Windows; and+`fc-list` on systems with Fontconfig. Search the relevant font locations or use the operating+system's font information to identify the face and file. A local `.ttf`, `.otf`, `.woff` or `.woff2`+face can enter the same asset path as a supplied font. A `.ttc`/`.otc` collection contains multiple+faces; the current Font Surface has no collection-face selector. Obtain the intended standalone+face, or export it with a font tool when permitted, before declaring it.++## Find a face when the available choices do not fit++Start with the user's brand assets and the relevant local or bundled faces. If the work calls for+another face, look at the foundry's or an open-font project's official specimen and download. Check+the actual script coverage, available weight/style and intended use, then bring the chosen file into+the project. Keep its source and license with it, especially when sharing the editable project.+Downloading a selected face as an asset is enough; installing it system-wide is optional.++Font choice and treatment work together: compare the actual caption wording, its line width,+character detail and contrast with the image. Good Han glyph coverage alone does not make an+English font-size, spacing or outline recipe suit Chinese text.++## Emoji presentation`emoji="color"` adds a color face; `emoji="mono"` chooses monochrome. Some symbols have both textand Emoji presentation. Write the intended Unicode sequence, such as `☎️`, when its color form isdiff --git a/skills/hypit/references/production/media.md b/skills/hypit/references/production/media.mdindex 03df9ab6..2550550e 100644--- a/skills/hypit/references/production/media.md+++ b/skills/hypit/references/production/media.md@@ -2,6 +2,7 @@Read this when admitting files, connecting generated media, choosing streams, or editing a clipbefore using it in a Track or a model reference. [Tracks](tracks.md) covers placement and playback.+For a source video at a link, read [video download](video-downloads.md).For acquiring website screenshots, page recordings or local HTML graphics, read[browser capture](browser-capture.md).diff --git a/skills/hypit/references/production/rendering.md b/skills/hypit/references/production/rendering.mdindex e7a2240f..a3e65297 100644--- a/skills/hypit/references/production/rendering.md+++ b/skills/hypit/references/production/rendering.md@@ -34,6 +34,41 @@ Presents, so moving these Film children does not reorder the picture.`main.composition` is the assembled work, usable in Studio. `final.video` asks for an encoded video.A compatible Composition from another component can also feed the render Surface.+## Compose an authored animation++A Film needs a time axis, whether or not it contains speech or prepared media. For a speech-led piece,+continue to pass `semantic={speech.semantic}`: it provides both the real performance time and the+context in which Tracks resolve Script references. For a pure MG piece, declare a ProgramSpace and+pass `space` to the components, Film and Render:++```svml+<import as="time" from="@hypit/program-space@1"/>+<time:Space id="animation" frame-rate="30" duration="8s"/>++<!-- conversation is the project's own visual component. -->+<chat:Scene id="conversation" space={animation} canvas={canvas} font={font}+ during="program" title="Launch crew">+ <chat:Message id="question" sender="Maya" side="left" at="0.5s" text="Ready?"/>+ <chat:Message id="answer" sender="Leo" side="right" at="2s" text="Let's go."/>+</chat:Scene>+<film:Film id="main" canvas={canvas} space={animation} appearance={look.film.main}>+ <film:Track source={conversation.track}/>+</film:Film>+<render:Video id="final" composition={main.composition} space={animation}/>+```++The example assumes the Canvas, font, Film Recipe and project package are declared. `time:Space`+accepts seconds, milliseconds or frames and must end on a frame boundary. `Clock` remains the+separate duration-free input for normalizing real media. Drawing code produces the picture at each+requested frame; the Film's background supplies the canvas color. With no AudioTrack, the delivered+video is silent. Render ranges and worker settings apply in the same way as for spoken work.++Media, Typography, Audio and the graphic Tracks accept this same time context. A Media Performance+specifically needs its SemanticTrack because that is where its prepared footage resides. Caption+uses its speech-linked document; authored chat text belongs to the chat scene. The working example+`examples/semantic-composition/chat.svml` and its `@example/chat-scene` package show the complete+code-only composition, including scrolling and arbitrary message arrivals.+## Choose a render interval in frames```svmldiff --git a/skills/hypit/references/production/studio.md b/skills/hypit/references/production/studio.mdindex 6fb1b2ee..cc544a92 100644--- a/skills/hypit/references/production/studio.md+++ b/skills/hypit/references/production/studio.md@@ -13,8 +13,9 @@ hypit-studio --run build.svrun```Supply `--runtime <profile>` when intentionally using a different Profile from the project's-`hypit runtime use` selection. Studio needs a Run whose selected targets reach one Film and a-resolvable semantic projection. An image-generation-only Run is not a Film view; several distinct+`hypit runtime use` selection. Studio needs a Run whose selected targets reach one Film with resolved+composition and time. Speech-led work includes a Script lane; a pure animation's ProgramSpace supplies+the clock for its component lanes. An image-generation-only Run is not a Film view; several distinctFilms need separate Runs or sessions.Open the URL actually printed by the process and retain it with the Run it serves. The defaultdiff --git a/skills/hypit/references/production/system.md b/skills/hypit/references/production/system.mdindex 16a2c86e..821fefc6 100644--- a/skills/hypit/references/production/system.md+++ b/skills/hypit/references/production/system.md@@ -22,12 +22,14 @@ to them before a performance has been generated.Once the media exists, normalization gives it a shared frame clock. A **SemanticTake** associatesthat media with one Script Segment and records its word and boundary positions in local frames.Speech Track assembles the Takes, translating their positions into a **SemanticTrack** for the-complete program. Its **ProgramSpace** supplies the program's time axis.+complete program. Its **ProgramSpace** supplies the program's time axis. A pure graphic animation can+instead declare a ProgramSpace directly and draw each frame through components; it needs no performance media.In spoken work, the performance carrying the main Script is the A-roll. A single presenter, aconversation with several speakers, and an independent narration can each carry this spine.Covering the speaker with B-roll does not change whose words establish time. Speech Track assembles-the relevant Takes into one semantic timeline while exposing their picture and sound separately.+the relevant Takes into one semantic timeline and publishes their original audio. Media or a project+component obtains the prepared picture from that semantic performance and decides how to present it.The speaker can occupy a small circular inset or appear as a cutout above a full-screen demonstration.That speaking performance still supplies the SemanticTake. A-roll describes this semantic role;screen area and stacking belong to its visual presentation.@@ -41,6 +43,11 @@ span, with start and end boundaries and no spoken words to locate.## Components turn those relationships into picture and sound+Choose each relationship at the scale that makes it useful. Script describes what an event follows;+Frames describe placement; a component owns shared layout, state and motion. The dependency graph+says which values that work needs. These structures can differ: a Source element can produce several+appearances, and one appearance can contain a whole scene of video and graphics.+A component gives an authored relationship its behavior. A ranking board can consume a phrase'sSelection to animate an entry; a reveal, flash and sound can share one Moment. Each interprets theevent according to its role. The board may keep the revealed answer visible after the entrance ends.@@ -49,8 +56,15 @@ Placement and appearance have their own inputs: a Frame says where the board belhow it looks, and supplied text or images say what it contains. This lets one behavior serve severalproductions while each production chooses its content and art direction.-Components publish visual and audio Tracks. Film assembles the wanted Tracks into a **Composition**,-and rendering turns that composition into the delivered video. Including performance audio lets+Visual and audio components publish Tracks. A visual Track groups named appearances; each appearance+owns its lifetime, paint order and internal element tree. A moving video and its diagram can form+one scene, with independent Caption beside it. Media provides ordinary presentation, and a project+component can own the shared behavior of a more specific scene. [Component design](component-design.md)+explains that choice; [drawing a component](component-visuals.md) shows both structural elements and+HTML/CSS programs with frame-driven behavior.++Film assembles the wanted Tracks into a **Composition**, and rendering turns that composition into+the delivered video. Including performance audio letsit continue under B-roll; a silent covering picture changes only the visible layer.[Tracks](tracks.md) explains the available roles. [Spatial layout](spatial.md) anddiff --git a/skills/hypit/references/production/track-authoring.md b/skills/hypit/references/production/track-authoring.mdindex 170af478..d0125e00 100644--- a/skills/hypit/references/production/track-authoring.md+++ b/skills/hypit/references/production/track-authoring.md@@ -9,11 +9,12 @@ and project package ownership. [Caption authoring](caption-authoring.md) covers## Start with the author-visible behavior-Prefer semantic inputs when the component responds to the video's meaning. A comparison can occupy+Prefer semantic inputs when the component responds to the words or performance. A comparison can occupya Selection; a verdict can trigger a Moment; the whole board can live for a Segment. Expose thosechoices on the Surface and pass their projected Windows or Instants to the implementation. This-keeps the component useful when a new performance changes the pace. Clock-based inputs remain-appropriate for behavior whose intention is an explicit time or duration.+keeps the component useful when a new performance changes the pace. In an authored animation,+content events carry their own reading rhythm. Their Instants and Windows enter the same component+inputs; durations and frame offsets direct how a change unfolds.Write a small intended Source use before implementing it. A new score strip might have one Style,an outer Window, preset scores and score-changing Moments. Decide whether its items appear briefly,@@ -53,6 +54,12 @@ This separation lets one Moment drive an answer reveal, a short sound and a flasreceives its own appropriate projection, but all refer to the same authored event. Changed speechmoves the event without asking each component to search for a word or inspect the Script parser.+For a component that also serves authored animation, `resolveTemporalContext` and `createTemporalSpace`+from `hypit/temporal-markup` supply the chosen film clock. Clock expressions project directly through+that space; Script references use its semantic context. The drawing code consumes the resolved+values in either case. The installed `examples/semantic-composition/packages/chat-scene` demonstrates+repeated content children with their own events and a program drawn entirely in code.+For a Window consumer, `during={story.selection.example}` can take both semantic boundaries.`at={story.moment.answer} for="8f"` starts a short effect at a Moment. An Instant consumer may accept`at={story.moment.answer}` with no duration because it owns a state transition. Read the actual@@ -71,8 +78,8 @@ Then decide what its children mean:- a preset item may already occupy the initial state and need no reveal trigger.Document that meaning in the component. `preset` is the answer strip's package-owned initial-state-concept. An answer strip may sensibly accept only Moments for child reveals; expose the timing forms-that match the component's behavior.+concept. An answer strip consumes an Instant for a reveal that persists, while Media consumes a+Window for occupancy. Expose timing inputs whose consumption matches the behavior.The interview's project emoji strip illustrates this design: one outer Window, ordered answeritems, a placeholder asset and one icon per answer. Each Moment changes its own slot. The Track does@@ -147,21 +154,26 @@ The useful pieces of a project package are:| Vocabulary and preview | Explain the role and show a recognizable, configured example || Optional Studio Companion | Project meaningful editor entities, real parameter bindings and temporal lineage without changing video rendering |-For a semantic Window, call `createTemporalWindowProjection` in the Surface with the resolved-SemanticTrack and authored element. For an event, use `createTemporalInstantProjection`. Preserve-all returned `records`, `components` and `fragments`, and wire its returned `ref` into the domain-Fragment. Merely reading `ref` and dropping those drafts leaves no producer for that value.--Validate the temporal forms the component actually accepts. The answer strip, for example, checks-that `at` references a Moment before using the shared helper; it intentionally does not accept a-Selection boundary. Keep a child `subjectId` meaningful to the component while qualifying graph ids-by the owning Track so two instances cannot collide. The exact helper options live in-`hypit/temporal-markup`.--Project ProgramSpace from the SemanticTrack once within the Fragment. Domain Producers then receive-that space and traced Windows/Instants, alongside Canvas/Frame, Style and explicit content inputs.-If the component consumes repeated children, a finite create/append/finalize graph is one established-pattern: each operation retains declared ports, and every child's media remains a real graph edge.+Resolve the Track's `semantic` or `space` through `resolveTemporalContext`, then use+`createTemporalSpace` once to obtain the shared ProgramSpace. A spoken composition normally supplies+`semantic={speech.semantic}`; an authored animation can supply `space={animation}`. This choice+belongs to the Surface. The visual Producer consumes space and projected time, not Script syntax.++For each Window, call `createTemporalWindowProjection`; for an event, use+`createTemporalInstantProjection`. Pass the resolved context, the shared `space`, the child element+and `resolveReference`. Preserve all returned `records`, `components` and `fragments`, and wire the+returned `ref` into the domain Fragment. The common `at` accepts a Moment or an authored duration+from program start. Selection and Segment boundaries use `boundary="start"` or `boundary="end"`.+A Moment needs the semantic context that locates its Script anchor.++Keep each child's `subjectId` meaningful to the component while qualifying graph ids by its owning+Track, so multiple instances can coexist. A finite create/append/finalize graph supports any authored+number of messages or cards with ordinary fixed Producer ports. The exact helpers and vocabulary+live in `hypit/temporal-markup`; the `@example/chat-scene` package demonstrates both time sources.++A scene may publish computed event times when another component needs them, just as it publishes a+Track. This shares pre-render data. When the author already specifies a common trigger, consumers+can share that input directly. Expose additional outputs for a real composition relationship.For persistent state, reason about a requested frame directly. For example: outside the outer Window,draw nothing; inside it, each slot shows its preset/activated answer or its placeholder. Apply andiff --git a/skills/hypit/references/production/tracks.md b/skills/hypit/references/production/tracks.mdindex 61b44f6f..4d7d45dd 100644--- a/skills/hypit/references/production/tracks.md+++ b/skills/hypit/references/production/tracks.md@@ -222,6 +222,8 @@ can be chosen directly for a new visual role; making one is ordinary productionFor the selected family's exact attributes and Recipes, use `hypit vocabulary @hypit/caption-fine`and its installed README. [Caption craft](../playbooks/craft/captions.md) explains reading rhythm;+[Caption styling and coverage](caption-program.md) explains Role and Selection overrides, whole+Segments, word-specific styles and Mute;[Caption tracking](../playbooks/craft/caption-tracking.md) explains measured moving placement.## Persistent MG is more than another timed image@@ -244,7 +246,9 @@ uses that same separation when designing a new semantic component.## Assemble the intended peersFilm's domain assembly receives a Canvas, a ProgramSpace and a Film Recipe. The current `film:Film`-Surface takes `canvas`, `semantic` and `appearance`, deriving the space from the SemanticTrack.+Surface takes `canvas`, `appearance` and a time source: `semantic` derives the space from the+performance; `space` selects an authored ProgramSpace. Pure MG can consist entirely of visual+components. [Rendering](rendering.md#compose-an-authored-animation) shows the complete time setup.Include each desired visual and audiooutput explicitly. Listing a Track later does not move it to the front: absolute stacking is authoredinside the Track's Presents. Use intentional, distinguishable layer orders where things overlap.diff --git a/skills/hypit/references/production/video-downloads.md b/skills/hypit/references/production/video-downloads.mdnew file mode 100644index 00000000..7c4c6060--- /dev/null+++ b/skills/hypit/references/production/video-downloads.md@@ -0,0 +1,45 @@+# Downloading a video from a link++Read this when a reference or source clip lives on a video page. `hypit media fetch` saves the+video as a project file through yt-dlp. For a website's interface, scroll or interaction, use+[browser capture](browser-capture.md).++## Save the source video++```bash+hypit media fetch "https://example.com/watch?v=VIDEO_ID" \+ --to references/ad/source.mp4+```++Replace the example URL with the actual video link. Quote it so URL punctuation stays part of the+argument. The destination is relative to the current directory; the CLI creates parent directories+and requires a new output path. `--json` reports the saved path, source URL, duration, dimensions,+frame rate and audio presence.++The command fetches one video, including its audio when available, even when the link also belongs+to a playlist. It prefers H.264 and a resolution near 1080p; the source's available formats determine+the result. Destinations can use `.mp4`, `.mkv`, `.webm` or `.mov`. Downloading retains source timing;+it is separate from preparing material for a production's frame clock.++## Prepare the downloader++The Hypit Distribution includes `@hypit/yt-dlp` and its locked Python dependency. `uv` prepares that+dependency on first use. `ffmpeg` merges separate picture and sound streams, and `ffprobe` reads the+saved file. [Local tools](../environment/local-tools.md#supply-host-executables-at-machine-scope)+covers these executables on macOS, Windows and Linux. The command runs directly, without a Runtime+Profile, model credential or Build.++Supported sites and access requirements depend on yt-dlp and the source site. A failed download+includes the downloader's error. When a site needs additional download options, the installed+`services/yt-dlp/README.md` explains direct use of the packaged tool; the site's own download or+export can also supply the same local file.++## Continue from the saved file++Keep the source URL and local path in the reference notes. Use the file for+[reference understanding](../creation/reference-video.md): transcription, timed frames and grids all+refer to that same source clock. Reuse the saved file when returning to the reference.++When the downloaded clip becomes material in the new video, declare it as `media:Video` and follow+[media preparation](media.md). The composition then places the prepared material against the+target's events.