Skip to content

armgit / hypit

Public Imported from GitHub
0

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.

docs(skill): clarify direction, paid scope and package sharing

kashorin05cf411dde76
diff --git a/README.md b/README.md
index 216628e3..6d81f8fb 100644
--- a/README.md
+++ b/README.md
@@ -139,7 +139,7 @@ Or start without a reference video:
/hypit Make a ranking video that puts Hypit in S tier.
```
-Your agent can check the environment, request only the credentials the video needs, preview the result, and build it.
+Your agent can check the environment, request the credentials the video needs, generate the material, and build the finished composition.
### **👉 [Get 100 FREE AI Avatars with unique voices](https://drive.google.com/drive/u/2/folders/18J9Fz7mkU3OQNJ-2Res3eIyFQ2cemIK5)**
@@ -174,10 +174,11 @@ Pull requests are welcome, and documentation, examples and translations count as
up an open issue or open one for what you want to work on, and we will help you land it.
[CONTRIBUTING.md](./CONTRIBUTING.md) has the setup, the checks CI runs and the pull request flow.
-When creating an original or reconstructed video, a component with clear, high reuse value across
-unrelated videos is a great candidate for contribution. You can ask your Agent to move it into
-Hypit's `packages/` folder, then submit it to us in a Pull Request. Ordinary one-off components can
-remain project-local.
+Creating a component is ordinary video-production work, and the component normally stays with the
+video project that owns it. When its owner wants to share it, the same package can be handed off as
+a versioned tarball or published under the owner's npm scope or private registry. Proposals for a
+component maintained in Hypit's official Distribution begin with an issue describing the shared
+product need; official inclusion is separate from normal community sharing.
The [Development Guide](https://hypit.ai/guide/develop/) covers the prerequisites, the daily
commands and the repository layout.
diff --git a/README.zh-CN.md b/README.zh-CN.md
index db036fb4..be8e2445 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -138,7 +138,7 @@ OpenAgents 等 Skill Hub 安装的是同一个 `skills/hypit/` 真目录。首
/hypit 做一个 ranking 视频,把 Hypit 排到 S 级。
```
-Agent 会检查环境,只索要这条视频需要的凭据,先给出预览,再执行构建。
+Agent 会检查环境,索要这条视频需要的凭据,生成素材并构建成片。
### **👉 [免费获得 100 个拥有独特音色的 AI 人物形象](https://drive.google.com/drive/u/2/folders/18J9Fz7mkU3OQNJ-2Res3eIyFQ2cemIK5)**
@@ -171,7 +171,7 @@ Agent 会检查环境,只索要这条视频需要的凭据,先给出预览
欢迎提交 Pull Request,文档、示例和翻译与代码同样重要。可以认领一个已有的 issue,也可以为你想做的事新开一个,我们会协助你把它合并进来。环境准备、CI 会跑的检查和 Pull Request 流程见 [CONTRIBUTING.zh-CN.md](./CONTRIBUTING.zh-CN.md)。
-在原创或复刻视频时,如果你觉得 Agent 创作的某个组件在无关项目中也有明确且很高的复用价值,它会是很好的贡献候选。你可以让 Agent 把它移入 Hypit 仓库的 `packages/` 文件夹,再提交给我们,发起一个 Pull Request。普通的一次性组件也可以留在项目内部。
+创建组件是正常的视频制作工作,组件通常留在拥有它的视频项目中。所有者希望分享时,可以把同一份包作为版本化 tarball 直接交付,也可以发布到自己的 npm scope 或私有 registry。希望某个组件由 Hypit 官方 Distribution 维护时,先通过 issue 说明它解决的共同产品需求;官方收录与普通的社区分享是两件事。
[开发指南](https://hypit.ai/zh/guide/develop/)说明了前置条件、日常命令和仓库结构。
diff --git a/docs/guide/author-packages.md b/docs/guide/author-packages.md
index 4c74e26b..db31aa03 100644
--- a/docs/guide/author-packages.md
+++ b/docs/guide/author-packages.md
@@ -248,6 +248,35 @@ authority.
The fixture deliberately uses explicit role filenames so a new author does not need to infer the
architecture from a large production package.
+## 10. Keep or share the same package
+
+Creating this package is ordinary production work. While it belongs only to the current video, keep
+it private under that project's `packages/`. When its owner wants another project to use it, compile
+the same package and either send a versioned `npm pack` tarball or publish it under the owner's npm
+scope or private registry. The consumer installs the chosen release with its package manager and
+commits the resulting lockfile; the logical Module import remains unchanged while that interface is
+compatible.
+
+For a public release, remove `private: true` and add ordinary npm discovery and ownership metadata:
+
+```json
+{
+ "description": "A speech-timed score strip for Hypit videos.",
+ "keywords": ["hypit", "hypit-author-package", "scoreboard"],
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/studio/score-strip.git"
+ },
+ "license": "MIT"
+}
+```
+
+Its README should include a copyable Source example, public outputs, visual evidence of the component,
+and the Hypit release used to check it. After installation, `hypit vocabulary <package>` reads the
+selected release's own Surface declarations. Package discovery, publication, versions and integrity
+remain with npm or the selected private registry; Hypit loads the package only when Source imports
+one of its logical offers.
+
## The complete literal shapes
The fixture is the authoritative small example. These are the same object shapes in abbreviated
diff --git a/docs/guide/providers.md b/docs/guide/providers.md
index a804141a..05f72e6d 100644
--- a/docs/guide/providers.md
+++ b/docs/guide/providers.md
@@ -146,7 +146,7 @@ An Endpoint may additionally return current Provider-shaped documents from `read
with only a web page keeps that page as its interface. `hypit pricing <run> --runtime <profile>` places
the material beside the Run's Needs without creating a Build. The Agent can calculate and explain the
cost from those two facts, while the user's decision remains the spending authority. The shared
-interface remains only a source URL and Provider-shaped JSON, so a newly supported relay does not
+interface carries a source URL, Provider-shaped JSON and an optional concise rate summary, so a newly supported relay does not
require a new Hypit pricing category.
`hypit plan --runtime <profile>` remains local and prints the Endpoint behind each request. Planning
diff --git a/docs/zh/guide/author-packages.md b/docs/zh/guide/author-packages.md
index 36ee46a0..786067bd 100644
--- a/docs/zh/guide/author-packages.md
+++ b/docs/zh/guide/author-packages.md
@@ -194,6 +194,32 @@ pnpm install --frozen-lockfile
`<import>` 只会 activate 作者词汇。它绝不授予网络、文件系统或凭据权限。
+## 10. 保留或分享同一份包
+
+创建这个包是正常的视频制作工作。只有当前视频需要它时,就把它作为私有包保存在项目的
+`packages/` 中。所有者希望其他项目使用时,编译同一份包,再通过版本化的 `npm pack` tarball
+直接交付,或发布到所有者自己的 npm scope 或私有 registry。使用方通过自己的包管理器安装选定
+版本并提交 lockfile;只要逻辑接口保持兼容,Source 中的 Module import 就不需要变化。
+
+公开发布时,移除 `private: true`,并补充普通的 npm 发现与归属信息:
+
+```json
+{
+ "description": "A speech-timed score strip for Hypit videos.",
+ "keywords": ["hypit", "hypit-author-package", "scoreboard"],
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/studio/score-strip.git"
+ },
+ "license": "MIT"
+}
+```
+
+README 应包含可直接使用的 Source 示例、公开输出、组件的视觉证据,以及验证时采用的 Hypit
+版本。安装后,`hypit vocabulary <package>` 会读取所选版本自己的 Surface 声明。包的发现、发布、
+版本和完整性继续由 npm 或选定的私有 registry 负责;只有 Source 导入了某个逻辑能力时,Hypit
+才加载对应包。
+
## 实现分流
没有高度相似 sibling 时,只读规范文档、已安装包的 vocabulary 输出和
diff --git a/docs/zh/guide/providers.md b/docs/zh/guide/providers.md
index db53ff3b..569364e9 100644
--- a/docs/zh/guide/providers.md
+++ b/docs/zh/guide/providers.md
@@ -137,7 +137,7 @@ Runtime 会先解析该 Endpoint 自己声明的凭据槽。它可以对真实
声明 `pricing: { kind: "local" }`。Endpoint 还可以通过 `readPricing` 返回 Provider 当前发布的
原始费率文档;只有网页的服务继续以该网页作为价格入口。`hypit pricing <run> --runtime <profile>`
把这些材料放在 Run 的 Needs 旁边,而且不会创建 Build。Agent 可以据此计算并解释费用,用户的
-决定仍然是支出授权。共享接口只有来源 URL 和保持 Provider 原始形状的 JSON,因此接入新的
+决定仍然是支出授权。共享接口包含来源 URL、保持 Provider 原始形状的 JSON 和可选的简短费率说明,因此接入新的
中转站不需要先给 Hypit 增加一种价格表分类。
`hypit plan --runtime <profile>` 仍然完全在本地执行并列出每个请求的 Endpoint。上游文件尚未
diff --git a/packages/seedance-kits/README.md b/packages/seedance-kits/README.md
index b0c0a234..8a670c04 100644
--- a/packages/seedance-kits/README.md
+++ b/packages/seedance-kits/README.md
@@ -90,6 +90,11 @@ Surface. Setting a prompt option cannot create a media reference or execute a po
## Speaker: edited UGC from one useful view
+For ordinary direct-to-camera social video, explicitly select
+`edit-rhythm: pause-trim-jump-cuts` as the starting rhythm. Read the Hypit Skill's Video direction page
+for the directing judgment, and the [Speaker template](kits/speaker-v1.svs) for the exact wording of
+its Recipe choices. Choose `performance` and `gesture` for the character's intended presence.
+
Reuse the same person-and-scene image and voice for ordinary Takes belonging to one UGC performance.
Each Take can begin from that shared reference and meet the others at a natural cut. There is no
required previous-tail-frame chain. Independent generation follows the intended edited form.
@@ -107,9 +112,10 @@ speaker.host {
```
`edit-rhythm: pause-trim-jump-cuts` asks the model for an edited pause-trim rhythm at phrase boundaries.
-It is compatible with a fixed camera and active performance. `continuous-take` is another authored
-choice, not a universal requirement. Actual speed changes, trimming or audio extraction are explicit
-media operations; selecting this Recipe does not perform them on the returned video.
+It is compatible with a fixed camera and active performance. The template uses `continuous-take`
+when `edit-rhythm` is omitted; select that value when the passage calls for a continuous
+shot. Actual speed changes, trimming or audio extraction are explicit media operations; selecting
+this Recipe does not perform them on the returned video.
## Podcast: two views and living listeners
diff --git a/skills/hypit/SKILL.md b/skills/hypit/SKILL.md
index 653486dd..b56dbb83 100644
--- a/skills/hypit/SKILL.md
+++ b/skills/hypit/SKILL.md
@@ -8,8 +8,8 @@ description: Make, adapt, and revise videos with Hypit from references or briefs
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; Studio is your
-editing room; the Runtime runs the production. Discover why the work holds attention, and make the
+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.
Bring the sensibility the video calls for: quick internet wit, warmth, social intuition, restraint,
@@ -17,8 +17,11 @@ or playful absurdity. Let it shape your ideas, images, words, and performances.
remain grounded, curious, imaginative, and discerning. Be perceptive about the whole, careful and
honest about the details, and curious when something does not yet make sense. Look for connections
that explain an unexpected choice. Draw on the relevant Skill references and keep what you learn
-in the project files as you go. Speak in the user's language, with warmth and specifics from what
-you have understood, what you are considering, and what the next useful action will resolve.
+in 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.
Most work Hypit is asked to clone is creator-led, phone-captured short-form UGC: spoken expression is
carried by one or more A-roll performances while B-roll, Caption and MG reshape what the viewer sees.
@@ -28,17 +31,29 @@ Use this as a practical prior when evidence is incomplete, not as a definition o
reference or Brief establishes independently narrated, speechless, animated or another kind of work,
direct that form on its own terms.
+For creator-led social video, favor compelling casting, a distinctive, appealing voice, and engaged,
+expressive delivery. Make the appeal perceptible in the words, voice, timing and visible reactions.
+When humor or surprise carries the idea, give it a setup, turn or response the audience can experience
+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.
-Creative direction and installed expression answer different questions. When the work needs a
-generated picture or video, A-roll, B-roll, Caption, MG, voice or sound relationship, read the Craft
-that owns what it should accomplish. Then use installed vocabulary and package-local documentation
-for the exact Surface, inputs and limits. Knowing how to call a model or component does not supply the
-directing judgment, and Craft does not replace the installed declaration.
+Before writing or adapting an image prompt, read
+[Image direction](references/playbooks/craft/image-direction.md) and apply it to the intended picture,
+including when starting from an existing project's prompt. For phone-footage images, use its
+recommended paragraph structure and assemble the fixed capture wording through its Kit.
+Before choosing, designing or changing a character's voice, read
+[Voice direction](references/playbooks/craft/voice-direction.md). Before writing or adapting a video
+prompt, performance Recipe or action, read [Video direction](references/playbooks/craft/video-direction.md)
+and the selected Kit's wording and choices. Apply these references when adapting earlier work as well.
+For A-roll, B-roll, Caption, MG or sound relationships, read the Craft that owns what the work should
+accomplish. Use installed vocabulary and package-local documentation for
+the exact Surface, inputs and limits. Craft supplies directing judgment; package documentation
+supplies the means to express it.
Treat existing project prompts and Recipes as earlier directing choices. Compare their assumptions
with the current Brief, Treatment and relevant Craft, and carry them forward while the same artistic
relationship still serves this work.
@@ -51,9 +66,9 @@ crafts explain resolution and duration choices.
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 before asking for it. Explain related missing capabilities together, using the actual account,
-local and hosted options and their consequences for this piece. Watching supplied material and
-developing its interpretation can proceed while that setup is being resolved.
+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.
## Understand and direct
@@ -70,12 +85,22 @@ ideas while preserving the details that make them work.
The Brief holds the user's goal; the Treatment is your creative answer. Clone work often means
"make this with my face" or "use my product." Reconsider the argument, words, images and graphic
relationships for that request. The reference helps explain what works; the new performance supplies
-the new timing. Give generated media strong direction through Craft, reference images and prompts
-before submitting the requests.
+the new timing.
+
+**Quality through direction.** Establish the intended material through thoughtful image and
+performance prompts, Script pronunciation, voice references and visual reference relationships.
+Resolve these creative choices while authoring the requests. Carry the generated assets forward as
+the material of the production, then refine how their arrangement expresses the Treatment.
## Compose and refine
-Build around the directed material and existing Outputs. Watch how MG, Caption, B-roll, Typography
+When the Script, prompts, references and requested durations are ready, submit the material work
+within the agreed commission. Develop components, Recipes and semantic arrangement while generation
+runs. Plan shared framing needs in Treatment and direction; judge the actual overlap of pictures and
+graphics 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
and 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 the
passage. Adjust the owning Source or component to improve those relationships. Reuse produced media
@@ -84,6 +109,11 @@ lets B-roll cover the explanation it supports. The composition is ready when its
carry the Treatment clearly and compellingly. Reconsider Treatment when the design itself needs to
change; 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)
+explains how semantic events make these compositions reusable.
+
Create project components as normal production work. Use the most representative available media
for the question being explored, and carry useful findings back to their owning project documents.
Environment, creation and production are rooms to revisit whenever the current question leads there.
@@ -92,15 +122,14 @@ practical, revisit that choice and carry the improvement into the work and its n
## Standing responsibilities
-- **Money.** Before paid work, including transcription, explain the actual requests,
- selected Endpoints, and the current Provider pricing information available for them. Use `hypit plan`
- with the selected Runtime Profile, then `hypit pricing` when its Providers expose machine-readable
- material; interpret that material against the listed Needs instead of treating it as a system verdict.
- Pricing availability is not a Build gate. Proceed under existing authorization that covers the work
- and cost; obtain it when missing. Additional generation needs an explicit decision covered by that
- authority. A request to rebuild or fix downstream work
- does not by itself authorize regenerating unchanged media. A Provider or billing-account change is
- a separate user choice; the Runtime Profile reference below owns how that choice is made.
+- **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;
+ [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
@@ -133,7 +162,9 @@ practical, revisit that choice and carry the improvement into the work and its n
- **Done means watched.** Watch the actual deliverable and judge it against the Brief, Treatment,
and relevant reference relationships. Judge its clarity, visual hierarchy, timing, character,
and suitability for publishing. Deliver the work with the important choices
- and limitations explained.
+ and limitations explained. Alongside the finished video, show the editable production in
+ [Studio](references/production/studio.md#show-the-finished-work) when it is readily accessible
+ to the user, so they can see how the piece is arranged and what they can change.
## Where the current question is answered
@@ -147,9 +178,10 @@ practical, revisit that choice and carry the improvement into the work and its n
| 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` |
-| writing or revising `<script>`: Segments, Roles, Dual Text, `||` Caption Cues, word attributes, Selections, Moments, empty passages, or measured delivery | `references/creation/script-and-time.md` |
+| writing or revising `<script>`: wording and pronunciation, Segments, Roles, Dual Text, `||` Caption Cues, word attributes, Selections, Moments, empty passages, or measured delivery | `references/creation/script-and-time.md` |
| project layout, picking work back up, or handing an editable production to someone else | `references/creation/project-files.md` |
| directing a generated person, setting, product, B-roll image, camera view, visual reference or image prompt | `references/playbooks/craft/image-direction.md` |
+| choosing, designing or adapting a character's voice, its appeal, vocal qualities or casting sample | `references/playbooks/craft/voice-direction.md` |
| 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` |
@@ -160,8 +192,9 @@ practical, revisit that choice and carry the improvement into the work and its n
| writing Sources, Recipes, and Runs, reusing produced work, adding a component | `references/production/authoring.md` |
| imports, output references, literal values or Recipe rules | `references/production/source-syntax.md` |
| choosing an existing Prompt Kit, assembling its wording or authoring a new one | `references/production/prompt-kits.md` |
-| Run syntax, Targets, Candidates, Run Fragments or substitute media for a preview | `references/production/runs.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` |
+| 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` |
diff --git a/skills/hypit/references/creation/brief.md b/skills/hypit/references/creation/brief.md
index ce371d8c..4cd7a56e 100644
--- a/skills/hypit/references/creation/brief.md
+++ b/skills/hypit/references/creation/brief.md
@@ -31,6 +31,13 @@ facts leave materially different goals, private facts, meaningful value choices,
spending authority unresolved. Routine casting, art direction, shot choice, Caption treatment,
component design, prompts, and implementation belong to the Agent.
+Preserve the user's agreed paid scope here as a production constraint: the billing accounts identified
+by non-secret labels or Endpoint references, the work they cover, and the accepted estimate, range or
+budget. Retain any limits the user attached to that agreement. Distinguish your proposed estimate
+from what the user has accepted, and an estimate from a firm spending ceiling. Keep the agreement
+current when the user changes it so another conversation can continue under the same authority.
+[Builds](../production/builds.md#work-within-the-agreed-paid-scope) owns how it applies to paid work.
+
## Treatment is the director's answer
`TREATMENT.md` turns the Brief, relevant reference understanding, and current creative judgment into
diff --git a/skills/hypit/references/creation/project-files.md b/skills/hypit/references/creation/project-files.md
index c40b8c76..48e0fc3e 100644
--- a/skills/hypit/references/creation/project-files.md
+++ b/skills/hypit/references/creation/project-files.md
@@ -99,12 +99,14 @@ referenced in place; its documentary role does not require a duplicate.
Typography, MG, Effect and Audio behavior belong to the same connected account.
- `transcript.json` is word-level speech evidence. It is evidence, not the director's interpretation.
- `evidence/` contains only media worth reopening, with ordinary human-readable names.
-- `BRIEF.md` preserves the user's goal, facts, constraints, and requested changes.
+- `BRIEF.md` preserves the user's goal, facts, constraints, requested changes and
+ [agreed paid scope](brief.md#brief-preserves-user-authority).
- `TREATMENT.md` is the director's current answer to the Brief: the intended new piece in complete
creative terms, before implementation details.
- `authors/`, `recipes/`, and `runs/` are the exact production implementation.
- `PROGRESS.md` is a short photograph of the work now: the live question, what remains to examine or
- make, next useful action, real blockers, active Build ids and reusable Results. When handing work
+ make, next useful action, real blockers, active Build ids and reusable Results. Keep cost information
+ relevant to the remaining work here when it affects the agreed budget. When handing work
over, retain the relevant Run and Runtime Profile, exact Build id and public Output names needed
to continue. Run Candidates own
the actual reuse choices; the note points to them. Established conclusions belong in their owning
diff --git a/skills/hypit/references/creation/reference-video.md b/skills/hypit/references/creation/reference-video.md
index 9c91208e..ed2420ea 100644
--- a/skills/hypit/references/creation/reference-video.md
+++ b/skills/hypit/references/creation/reference-video.md
@@ -39,9 +39,19 @@ things belong together.
## Make time visible
-Use `hypit transcribe` to establish word-level times for spoken work. Keep that transcript beside the
-reference: it is the temporal spine for connecting speech to cuts, illustrations, reveals and
-emphasis. For speechless work, locate meaning through actions and changes in the scene.
+Use `hypit transcribe` when understanding a spoken reference. Its wording and word-level times give
+a strong starting point for following the argument and connecting speech to cuts, illustrations,
+reveals and emphasis. Keep that transcript beside the reference and interpret its wording with the
+surrounding argument, visible names and supplied context. Small transcription errors can coexist
+with a clear understanding of what the passage means.
+
+WhisperX's recognized spelling reflects the recognizer's interpretation of the audio. Coined words
+and unfamiliar names are especially prone to substitutions, so a spelling difference alone cannot
+establish a pronunciation error. The transcript helps recover the reference's content and locate
+its moments. For the new work, [Script pronunciation](script-and-time.md#write-the-intended-pronunciation)
+expresses the words and readings the generation request should perform.
+
+For speechless work, locate meaning through actions and changes in the scene.
The local `hypit media` commands expose the source at the scale needed:
diff --git a/skills/hypit/references/creation/script-and-time.md b/skills/hypit/references/creation/script-and-time.md
index 360d4aa9..8273ad48 100644
--- a/skills/hypit/references/creation/script-and-time.md
+++ b/skills/hypit/references/creation/script-and-time.md
@@ -9,7 +9,7 @@ and edge cases.
[Source syntax](../production/source-syntax.md) covers the surrounding imports, references, Recipes
and Runs; [Tracks](../production/tracks.md) covers the consumers of Script meaning.
[Media preparation](../production/media.md) explains connecting actual footage to a Segment, and
-[Runs](../production/runs.md) explains choosing estimated timing for a layout study.
+[Runs](../production/runs.md) explains targeting material and reusing produced Takes.
## Script is the target's sole verbal authority
@@ -18,25 +18,28 @@ visual Style parameters, prompts, or provider decisions. Semantic word attribute
`useful{emphasis}` can identify a word's role for a Caption family. Brief may preserve required claims and Treatment may describe
the purpose of a passage, but the adopted wording appears in Source only once.
-Use Script's distinct authoring concepts for distinct jobs:
+Choose Script structure from the thought being expressed and the performance carrying it:
-- a **Segment** is a named structural passage whose accepted media can become one SemanticTake;
-- a **Role Cue** says who speaks a turn without creating a character or choosing a voice;
+- a **Segment** groups a performable passage around its thought, delivery and action; its accepted
+ media can become one SemanticTake;
+- a **Role Cue** assigns a spoken turn to a performer and carries that label into the model's dialogue;
- **Dual Text** gives one authored unit separate display and pronunciation text;
- `||` says that one on-screen **Caption Cue** hands off to the next after a complete Alignment Unit;
- a **word attribute** gives a Caption family an authored role on one displayed word;
-- a **Selection** names a semantic range;
-- a **Moment** names a semantic point.
+- a **Selection** names the span of meaning an element serves, such as a demonstration covering an
+ explanation or a comparison held through a claim;
+- a **Moment** names an event such as an answer or verdict, where graphics, sound or effects can
+ respond together. The component decides how the resulting state continues.
```svml
<script id="story">
<hook>
- <HOST> @claim! I made @proof <Hypit | hi pit> || work overnight @/proof.
+ <HOST> @claim! I made @proof <Hypit | Hai-Pit> || work overnight @/proof.
</hook>
</script>
```
-Here the viewer reads `Hypit` while the performance says `hi pit`. The pair is one indivisible
+Here the viewer reads `Hypit` while the performance says `Hai-Pit`. The pair is one indivisible
Alignment Unit. `||` ends one on-screen Caption Cue after that unit and lets the next Cue begin with
`work`; `proof` remains one semantic range, and `claim` is a semantic point that other layers can use.
@@ -97,6 +100,29 @@ one Han, Hiragana or Katakana character per lexical unit; compounds, decimal num
side of Dual Text preserve their own lexical structure. This is why Cue breaks, word attributes and
semantic markers attach to complete authored units instead of punctuation or visual line positions.
+## Write the intended pronunciation
+
+Choose pronunciation while writing the Script. For coined names, unfamiliar brands and abbreviations
+whose reading needs direction, use Dual Text to keep the intended display spelling and give the
+performer a clear spoken form. Write that form as readable words, syllables or letter names in the
+performed language. This lets the request express the sound the work needs.
+
+```svml
+<script id="story">
+ <opening>
+ <HOST> I make videos with <Hypit | Hai-Pit> and write with <ChatGPT | chat G P T>.
+ </opening>
+ <closing>
+ <HOST> Here is what I made with <Hypit | Hai-Pit>.
+ </closing>
+</script>
+```
+
+Each pair applies to that occurrence. Carry the chosen spoken form into every occurrence of the
+name, including other Segments, so separately generated performances receive the same direction.
+The right-hand wording reaches the model through the Segment's `.dialogue`; Caption keeps the
+display spelling. Settle these readings before measuring the Script and requesting its performance.
+
## Use the Script's deliberate projections
One Script publishes the full Narrative and the narrow views needed by the rest of the work:
@@ -111,6 +137,27 @@ One Script publishes the full Narrative and the narrow views needed by the rest
| `{story.selection.proof}` | The named semantic range. |
| `{story.moment.claim}` | The named semantic point. |
+For example, this Segment inside `story` assigns two speaking turns:
+
+```svml
+<exchange>
+ <HOST> Let me show you.
+ <GUEST> That looks much easier.
+</exchange>
+```
+
+`{story.segment.exchange.dialogue}` supplies:
+
+```text
+HOST: Let me show you.
+GUEST: That looks much easier.
+```
+
+Pass that Text to the speaking prompt. In action direction, relate HOST and GUEST to the supplied
+character views and voices. The selected [Prompt Kit](../production/prompt-kits.md) owns its reference
+order; [podcast direction](../playbooks/formats/two-person-podcast.md#direct-conversation-inside-a-take)
+shows how those roles and references form one performed exchange.
+
These are projections of one authored Script, not copies to maintain. The performance request,
Caption system, and semantic timing therefore remain connected even when their visible and spoken
wording differ.
diff --git a/skills/hypit/references/creation/transformations.md b/skills/hypit/references/creation/transformations.md
index f47ce313..5bbd3416 100644
--- a/skills/hypit/references/creation/transformations.md
+++ b/skills/hypit/references/creation/transformations.md
@@ -60,7 +60,7 @@ its setup and payoff fit the new casting and Brief. The new person may invite a
a better version of the joke. A supplied pet might express the same confidence through a planted
pose, gaze, or comic authority. Let the new character make the work feel inhabited.
-The portrait supplies visual identity; [voice direction](../playbooks/craft/voice-and-performance.md)
+The portrait supplies visual identity; [voice direction](../playbooks/craft/voice-direction.md)
uses supplied audio or a voice chosen for the target performance. The original photo's setting and
pose may give way to the shot the video needs. Use [reference relationships](../playbooks/craft/generated-dependencies.md)
to decide where the supplied image enters that production.
diff --git a/skills/hypit/references/environment/profile.md b/skills/hypit/references/environment/profile.md
index 7af9710e..d63f67ec 100644
--- a/skills/hypit/references/environment/profile.md
+++ b/skills/hypit/references/environment/profile.md
@@ -154,23 +154,26 @@ choose a Profile from a familiar filename or from another project above it.
## Choose the practical capability path with the user
-Inspect the selected Profile, configured credentials, and current Endpoint diagnoses before asking
-the user to set up anything. For a typical generated reconstruction, assess word alignment, image
-generation, and video generation together so that solving one missing
-capability does not conceal another. Keep a working choice. When capabilities are missing, explain
-all material consequences in the language of the work and ask which supported Provider accounts or
-Keys the user already has and whether local WhisperX is practical. Present the related gaps together
-rather than as serial setup interruptions, and revisit the choice when the user's intention or the
-available environment materially changes. Present only choices that materially differ in cost,
-privacy, setup time, or control.
+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. Explain that its first preparation may install a runtime and download model
- weights; `local-tools.md` owns the bounded setup and repair guidance.
+ 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. Authentication and available quota still need to
- be established for the selected account.
+ 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.
@@ -180,6 +183,11 @@ quota, rate limit or service failure never authorizes that switch or a different
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 references
A Profile names a Credential Store and key; the secret stays in that store. The writable OS store
@@ -233,20 +241,12 @@ remote service. Read `../production/builds.md` for planning, spending authority,
## Be honest about the available production
-When a capability is absent, explain the creative consequence and offer the choices that actually
-exist:
-
-- select a supported Provider using the user's own account;
-- use the official HypiHub Endpoint when the user has chosen and authenticated it;
-- use a local implementation such as WhisperX when the machine can support it;
-- use deterministic HyperFrames components when an MG-, Caption-, or Typography-led piece genuinely
- fits the user's intent;
-- stop before promising a reconstruction that needs unavailable generation.
-
-With no image or video generation account, HyperFrames can still generate deterministic MG, Caption,
-and Typography when that form fits the requested work; it does not replace generated A-roll or B-roll.
-Word alignment establishes the timing needed to attach semantic events to real speech. Explain a
-missing capability through the work it prevents, and continue independent work while resolving it.
+When a capability is unavailable, explain the part of the requested result that depends on it and
+the practical choices available. Reference frames, supplied text and product material can still
+support interpretation, Script and visual planning. Existing media can support composition with
+HyperFrames MG, Caption and Typography when those serve the Brief. Generated performances and
+measured speech timing depend on the corresponding capabilities becoming available. Keep the
+completed work and the remaining dependency clear so the user can decide how to proceed.
When the user brings another model, service, or Key, use
[Models and Providers](model-and-provider.md) to distinguish credential setup, Endpoint configuration,
diff --git a/skills/hypit/references/playbooks/craft/image-direction.md b/skills/hypit/references/playbooks/craft/image-direction.md
index 58c82237..4dbbb9e4 100644
--- a/skills/hypit/references/playbooks/craft/image-direction.md
+++ b/skills/hypit/references/playbooks/craft/image-direction.md
@@ -35,7 +35,8 @@ choices so they are easy to revise. The [café example](examples/image-direction
shows one compact arrangement; a derived view can say even less when its reference already supplies
the person and world.
-For these phone-video portraits, four paragraphs give the direction a clear shape:
+For these phone-video portraits, use this recommended four-paragraph structure. Keep the capture
+wording intact; write the other three with the few anchors this picture needs:
| Paragraph | Directing question | What to express |
| --- | --- | --- |
@@ -83,7 +84,7 @@ recessed entrance and tables along the pavement implies surfaces, depth and a wa
In a record shop, shelves turning into an aisle and a nearby browsing bin can do the same work.
Choose the few features that make this particular view come to mind.
-Surface texture and spatial structure contribute different things. Grain or plaster texture can
+Surface texture and spatial structure contribute different things. Wood grain or plaster texture can
give a surface variation while the whole background still reads as one flat plane. A door recess,
window bay, shelving return or relationship between furniture and the room can establish how that
space continues. Describe the useful feature directly. A broad wall can belong naturally to this
@@ -116,6 +117,13 @@ give direction; casual additions such as "bright," "deep," "dark," or "light" ca
image when only a hue was intended. The Kit supplies the natural-lighting premise. Add a particular
time, weather condition, or light event when the intended scene actually needs it.
+For clean phone-footage realism, build atmosphere through the scene's colors, materials and character.
+Wood grain, fabric weave and foliage give actual objects tangible detail. Added "fine sensor grain"
+asks for noise across the image; "natural falloff" and "dim" or "dark" lighting directions can push
+the picture toward gray, muddy shadows. These choices can undermine the clarity of this photographic
+style. Let the fixed capture paragraph establish its natural lighting and video texture, and put the
+scene's distinctive detail into the people, place and objects.
+
For this photographic style, prefer colored, textured materials over broad white or flat gray areas:
colored plaster, wood, fabric, and foliage can supply surface variation and a more deliberate palette.
Choose what complements the subject. A texture adjective alone does little for a weak color pairing.
diff --git a/skills/hypit/references/playbooks/craft/video-direction.md b/skills/hypit/references/playbooks/craft/video-direction.md
index ae457f07..181470a6 100644
--- a/skills/hypit/references/playbooks/craft/video-direction.md
+++ b/skills/hypit/references/playbooks/craft/video-direction.md
@@ -1,8 +1,53 @@
# Directing generated video
-Read this when turning useful visual references, voice identity, Script or a visual idea into living
-speech, interaction, camera behavior or silent action. An image can establish who and where; generated
-video decides what visibly and audibly happens over time.
+Read this before writing or adapting a video prompt, performance Recipe or action. An image can
+establish who and where; generated video brings the Script and visual idea to life through speech,
+interaction, camera behavior or silent action.
+
+For creator-led social video, favor an engaged, expressive performance that draws the viewer into
+what is being said. Give personality and humor an audible or visible expression: a revealing choice
+of emphasis, an amused reaction, a turn in attitude or a payoff in the delivery. Let the audience
+experience the idea through the performed words and actions.
+
+## Direct the reason for an action
+
+Start with the social situation and attitude: affectionate ridicule, candid surprise, playful
+skepticism, delighted conviction or another relationship the audience can recognize. Write a short
+passage direction around that attitude and the few reactions through which it develops. An eager
+lean, an incredulous look, a knowing shrug or a sudden smile can make the spoken idea tangible.
+
+Let the meaning motivate the change: a claim invites skepticism, an example wins the speaker over,
+or a final judgment lands with confidence. A description such as "funny" or "ironic" becomes useful
+direction when the words, expression or timing give the viewer something to recognize. Choose the
+decisive beats and let the model perform the connecting behavior naturally.
+
+For example, alongside a Script that moves from a claim through a demonstration to a verdict:
+
+```text
+The host is eager to show a friend why this works. Give the bold claim a playfully skeptical look,
+brighten as the example proves it, then land the verdict with delighted certainty and a knowing nod.
+```
+
+Carry the character, voice and useful physical relationships across Takes while directing the
+attitude each passage calls for. The same speaker can invite, question, tease and persuade as the
+argument develops. Stable framing leaves room for these changes in face, voice and posture.
+
+The prompt describes what this generation should make visible over time. Give a performer physical
+relationships with the camera, people, props and parts of the setting that actually exist in the
+generated scene. A Caption, icon, product card or other MG composed later can influence framing, but
+it is not an object for the performer to touch, watch or reveal inside the generated video.
+
+Capable video models can turn figurative wording into literal objects, events or transformations. Use
+concrete visible language for intended gaze, gesture, movement, camera behavior and cuts when a
+metaphor would introduce the wrong scene content. Social attitude and aesthetic shorthand remain
+useful when they direct performance; an imagined object or event belongs in the prompt when it should
+truly appear in the generated world.
+
+Natural emphatic gestures are usually more reliable than asking fingers to display an exact number.
+Let speech, Caption or MG convey the quantity while pointing and hand actions serve the performance.
+An encounter also has edges: someone interrupted can first be occupied, and someone finishing can
+begin to leave. Small causes make a clip feel like a piece of life rather than a pose bounded by the
+encoder.
## Give each input its own responsibility
@@ -11,7 +56,7 @@ video decides what visibly and audibly happens over time.
| Character-and-scene references | appearance, setting, framing and the physical state to preserve |
| Product, interface or other factual references | the visible facts that need continuity or exactness |
| Recurring voice references | a speaker's intended voice identity when the model accepts them |
-| Script dialogue | the exact words and speaking turns for a visible performance |
+| Script dialogue | the exact words, intended pronunciation and speaking turns for a visible performance |
| Prompt Kit or Recipe | a reusable prompt relationship that fits this kind of work |
| Passage direction | attitude, attention, physical interaction, camera behavior and motivated cuts |
@@ -21,9 +66,13 @@ these inputs; use its installed vocabulary and package-local documentation for t
For a visible A-roll performance, the generated video normally carries the person's picture, exact
Script delivery and sound together. Give the request the useful camera image, the recurring Voice
-Reference when supported, and the Segment's dialogue. Voice Design establishes who the person sounds
-like; its short casting line does not need to repeat the finished Script. Independent speech is a
-different A-roll construction, described in [Voice and performance](voice-and-performance.md).
+Reference when supported, and the Segment's dialogue.
+[Voice direction](voice-direction.md) owns the casting and sample that establish who the person sounds
+like. The passage's direction gives that voice its current attitude and delivery.
+[Script pronunciation](../../creation/script-and-time.md#write-the-intended-pronunciation) explains
+how names and abbreviations receive the intended reading while keeping their display spelling.
+Independent speech is a different A-roll construction, described in
+[Voice and performance](voice-and-performance.md).
For silent B-roll, direct the visual event and omit speaking identity that the shot does not use. A
listener or reaction shot can remain silent while still breathing, noticing, adjusting posture or
@@ -53,36 +102,20 @@ model request. The current Distribution may provide model-specific Kit packages
reference order. [Prompt Kits](../../production/prompt-kits.md) explains using or authoring a Kit
without making it a model wrapper.
-## Direct the reason for an action
-
-Start with the social situation and attitude: affectionate ridicule, candid surprise, dry confidence,
-playful skepticism, quiet concentration or another relationship the audience can recognize. Then
-choose a few visible actions that communicate it. A restrained lean, open-palmed explanation, knowing
-shrug or short glance can carry more than elaborate choreography. Vibe establishes the performance;
-describe the decisive physical action when the story needs a handoff, reaction, entrance or exit.
-
-The prompt describes what this generation should make visible over time. Give a performer physical
-relationships with the camera, people, props and parts of the setting that actually exist in the
-generated scene. A Caption, icon, product card or other MG composed later can influence framing, but
-it is not an object for the performer to touch, watch or reveal inside the generated video.
-
-Capable video models can turn figurative wording into literal objects, events or transformations. Use
-concrete visible language for intended gaze, gesture, movement, camera behavior and cuts when a
-metaphor would introduce the wrong scene content. Social attitude and aesthetic shorthand remain
-useful when they direct performance; an imagined object or event belongs in the prompt when it should
-truly appear in the generated world.
-
-Natural emphatic gestures are usually more reliable than asking fingers to display an exact number.
-Let speech, Caption or MG convey the quantity while pointing and hand actions serve the performance.
-An encounter also has edges: someone interrupted can first be occupied, and someone finishing can
-begin to leave. Small causes make a clip feel like a piece of life rather than a pose bounded by the
-encoder.
+Read the selected template's wording when choosing its Recipe. Composition, camera, edit rhythm,
+performance and gesture choices shape different aspects of the footage. Choose them to support the
+intended delivery, and use action Text for the passage's particular meaning and reactions.
## Direct camera and cuts as part of the passage
-Creator footage can benefit from pause-trim jump cuts. A podcast can cut with a speaker or toward a
-meaningful reaction. A street interview can favor the guest and use the interviewer view for a
-reaction. Stable framing, expressive acting and frequent edits are compatible choices.
+For ordinary direct-to-camera social video, prefer pause-trim jump cuts at phrase boundaries. This
+edited rhythm keeps the explanation moving and gives the footage the immediacy of a creator's own
+cut-down recording. Stable framing, expressive acting and frequent edits are compatible choices.
+Use the selected Kit's documented Recipe choice to express that rhythm.
+
+A podcast can cut with a speaker or toward a meaningful reaction. A street interview can favor the
+guest and use the interviewer view for a reaction. An unfolding action or a held reaction may gain
+its effect from a continuous shot; choose that temporal shape when it serves the passage.
One generated video can contain multiple shots, several speaking turns or a split-screen composition.
One Segment is not one speaker turn or one camera shot. Conversely, several Takes can reuse the same
@@ -100,6 +133,8 @@ corresponding media operation and align the edited result before it becomes a Se
Use `hypit measure` on a spoken Segment at its intended pace, including time for meaningful
interaction, pauses and actions. [Script and time](../../creation/script-and-time.md#measure-before-choosing-durations)
owns the command, rounding and the relationship between estimated duration and real aligned time.
+Choose that pace from the intended performance and carry it into the voice and passage direction.
+Measurement sizes the words; emphasis, attitude and motivated reactions give their delivery character.
The target's delivery determines how much generated media the passage needs; the reference video's
seconds help explain its rhythm without becoming the target duration automatically.
@@ -111,7 +146,5 @@ exchange may divide where its thought turns. Preserve the intended meaning and e
supported duration.
After production, normalized media supplies the real envelope and alignment supplies word positions.
-Watch the result for engaged performance, correct speaking identity, legible interaction, intentional
-camera behavior and the intended energy. Correct words alone do not establish that the scene works;
-revise the visible or audible problem at the direction, reference, generation or media operation that
-owns it.
+Use that material and timing to compose the piece. [Composition review](../../production/review.md)
+owns judging how Caption, MG, B-roll and other layers work with the produced performance.
diff --git a/skills/hypit/references/playbooks/craft/voice-and-performance.md b/skills/hypit/references/playbooks/craft/voice-and-performance.md
index 36e717bd..71d72d61 100644
--- a/skills/hypit/references/playbooks/craft/voice-and-performance.md
+++ b/skills/hypit/references/playbooks/craft/voice-and-performance.md
@@ -2,6 +2,7 @@
Read this when deciding who performs spoken material, how a recurring person keeps one voice, or
whether an off-screen passage continues an A-roll performance or uses independent speech.
+[Voice direction](voice-direction.md) owns casting an appealing voice and writing its direction.
## Let the Segment reveal the A-roll
@@ -77,19 +78,16 @@ a voice merely by appearing in the picture; when that character speaks elsewhere
reference follows them into that performance.
When the user supplies the exact private voice they want, prepare a clean representative excerpt as
-the Voice Reference. Otherwise direct Voice Design from the person's role, energy, age range,
-language, accent, vocal texture, pace, and delivery. Voice Design acts as a broadly capable casting
-and voice-design partner; a public character type or an imagined voice can be designed directly.
+the Voice Reference. Otherwise use [Voice direction](voice-direction.md) to cast the character through
+Voice Design and choose its sample line. A public character type or an imagined voice can be designed
+directly.
About five seconds of clear, natural speech is usually enough to establish a useful reference while
remaining easy to reuse across models. Choose words that exercise the delivery the work needs. Keep
the sample free of other speakers, music, clipping, heavy room echo, and long silence. The selected
model's documentation owns any exact count, duration, or format limits for its references.
-Direct the voice from the intended character and performance. Appearance alone is not acoustic
-evidence, but the Agent can choose a voice that supports the person's role, personality, setting, and
-the work's tone. Once accepted, reuse that same Resource wherever the same person must sound like
-themselves.
+Once accepted, reuse that same Resource wherever the same person must sound like themselves.
## Let one reference support different performances
@@ -185,17 +183,14 @@ other relationships.
`../../creation/script-and-time.md` owns measurement, literal duration, and alignment. Once the
accepted performance has semantic time, its dependent layers follow the delivery that really
-happened. Repair a weak performance at its direction, wording, reference, or generation according to
-the visible and audible problem.
+happened.
## Carry the character through the performance
-Direct voice and visible performance toward the same character: pace, emotion, gesture, gaze and
-interaction with the scene. Carry that identity across recurring Takes while allowing the energy
-and delivery to develop with the conversation.
+[Voice direction](voice-direction.md#let-one-voice-express-different-thoughts) connects recurring vocal
+identity with changing delivery; [Video direction](video-direction.md#direct-the-reason-for-an-action)
+connects each passage's meaning with expression, gesture and interaction.
-Review covered passages with their picture and with the underlying speech source made clear. A clean
-mix cannot rescue the wrong performer, and a good voice sample cannot rescue an unconvincing Take.
-Use `sound-mix.md` for music, effects, ambience, gain, and the completed mix. Use
-`../../creation/transformations.md` for the broader question of which useful shots and identity
-references should directly condition another generation.
+Use [Sound and mix](sound-mix.md) for music, effects, ambience, gain, and the completed mix.
+[Transformations](../../creation/transformations.md) connects casting and reference choices to the
+target's argument, relationships and presentation.
diff --git a/skills/hypit/references/playbooks/craft/voice-direction.md b/skills/hypit/references/playbooks/craft/voice-direction.md
new file mode 100644
index 00000000..7fe7617c
--- /dev/null
+++ b/skills/hypit/references/playbooks/craft/voice-direction.md
@@ -0,0 +1,73 @@
+# Directing a voice
+
+Read this before choosing, designing or changing a character's voice, including when adapting a
+production with an existing Voice Reference. Cast a voice the audience will want to keep hearing.
+For creator-led social video, favor a distinctive, engaging presence that makes the words feel
+addressed to someone.
+
+## Cast the person through the sound
+
+Imagine who is speaking, whom they are addressing, and what makes their company compelling. A teasing
+friend, an infectiously curious guide, a charismatic challenger or a mischievous little creature can
+suggest a voice more vividly than a list of acoustic properties. Choose a vocal personality that
+belongs to this character and serves the piece's intended appeal.
+
+Give that appeal an audible expression: an inviting warmth, a quick wit, an infectious enthusiasm,
+or a confident bite. Energy can come from nimble phrasing, clear emphasis and a responsive attitude.
+The strength and shape of the presence should suit the encounter, from a lively recommendation to an
+intimate conversation.
+
+Look at the character reference and use the Brief to make the casting choice. A supplied voice can
+establish an exact identity. An existing project's voice can continue that identity when its casting
+still serves the new piece. For a new person or character, develop the voice that makes this role
+worth following. Keep the casting choice and the reference's role in Treatment and Source.
+
+## Compress the voice into a vivid direction
+
+A useful voice description is often one short paragraph: the vocal character and appeal, a few
+distinctive sound qualities, and the way they address the listener. Choose qualities that reinforce
+one coherent impression. Age range, pitch, accent, texture and diction are useful when they make the
+intended voice more specific.
+
+For example:
+
+```text
+A magnetic female host with a warm, lightly husky voice, talking to a friend she knows she can win
+over. Quick, playful phrasing with crisp emphasis and an audible smile. Conversational American
+English, full of curiosity and delighted conviction.
+```
+
+A different character can have a different kind of appeal:
+
+```text
+A rich, resonant storyteller's voice, warm and conspiratorial, as though sharing a discovery across
+a small table. Unhurried British English with precise articulation; curiosity lifts the important
+words and a knowing amusement colors the turns in the story.
+```
+
+These directions give the voice model a person and a relationship to perform. Preserve the qualities
+that define the casting while choosing the language and delivery density the actual work needs.
+
+## Let the sample carry the character
+
+Choose a short, natural line that gives the intended voice room to show itself. A curious question,
+an enthusiastic recommendation or a teasing judgment can establish both identity and the manner of
+speaking the work calls for. Write the intended pronunciation for unfamiliar names in Script before
+using the line as a sample.
+
+Voice Design uses that line to establish the reusable voice. The finished passages receive their
+own dialogue and direction. [Voice and performance](voice-and-performance.md#give-a-recurring-person-one-accepted-voice)
+owns reference preparation, reuse and the choice between visible A-roll and independent speech;
+the selected model's package documentation owns its exact inputs.
+
+## Let one voice express different thoughts
+
+Carry the same vocal identity through the work while letting each passage develop its own attitude.
+The speaker may draw someone in, challenge a claim, become delighted by an example, then deliver a
+confident verdict. Give those changes to the performance model through the passage's direction.
+
+[Video direction](video-direction.md#direct-the-reason-for-an-action) connects that attitude to gaze,
+gesture and interaction. For independent speech, the speech request carries the delivery direction.
+Choose time from this intended performance using
+[Script measurement](../../creation/script-and-time.md#measure-before-choosing-durations).
+The pace estimate sizes the passage; the voice and performance direction give it character.
diff --git a/skills/hypit/references/playbooks/formats/talking-head.md b/skills/hypit/references/playbooks/formats/talking-head.md
index 7fc666ef..9607e90e 100644
--- a/skills/hypit/references/playbooks/formats/talking-head.md
+++ b/skills/hypit/references/playbooks/formats/talking-head.md
@@ -16,6 +16,7 @@ or rotation. A vivid attitude and an easy speaking gesture give this settled vie
[idle principle](../craft/image-direction.md#choose-an-idle-state-for-the-encounter) relates that pose
to addressing the viewer; the generated performance can move and react within the encounter.
+Cast the person's vocal appeal with [Voice direction](../craft/voice-direction.md).
Use that same image and the person's recurring voice reference for every ordinary talking Take.
Each Take can return to the same useful visual premise and contribute another piece of the edited
performance.
@@ -34,10 +35,10 @@ The installed Kit package owns its exact assembly, reference order and Recipe ch
passage direction each contribute. A work whose camera, cast, or performance relationship differs can
use another Kit or ordinary authored direction.
-A fitting Speaker Recipe can combine stable framing with
-`edit-rhythm: pause-trim-jump-cuts`. The camera can
-stay fixed while the edit removes dead pauses and the performer remains expressive. This is a prompt
-instruction to the generator; it does not run an automatic trimming operation on the returned file.
+For this edited talking-head form, start with the Speaker Recipe's
+`edit-rhythm: pause-trim-jump-cuts`. The camera can stay fixed while the performer remains expressive.
+[Video direction](../craft/video-direction.md#direct-camera-and-cuts-as-part-of-the-passage) explains
+choosing the rhythm for the passage; the installed Kit documents the wording this option supplies.
Action supplies what the scene means to this person. For a teasing ranking host, amused disbelief,
a knowing look and a compact dismissive gesture are more useful than a limb-by-limb animation plan.
diff --git a/skills/hypit/references/playbooks/index.md b/skills/hypit/references/playbooks/index.md
index 61424122..553fff0a 100644
--- a/skills/hypit/references/playbooks/index.md
+++ b/skills/hypit/references/playbooks/index.md
@@ -23,6 +23,7 @@ not need a matching playbook before it can be understood or made.
| Read | When the current question concerns |
| --- | --- |
| [Directing generated images](craft/image-direction.md) | phone-video realism, character presence, image prompts, materials and palette, or preparing a useful visual reference |
+| [Directing a voice](craft/voice-direction.md) | casting an appealing voice, choosing its vocal character, writing Voice Design direction or selecting a sample line |
| [Voice and performance](craft/voice-and-performance.md) | how Segment performances create semantic time, who is A-roll, recurring voice identity, visual A-roll presentations, or genuinely independent narration |
| [Directing generated video](craft/video-direction.md) | choosing a generation relationship, directing visible performance or silent action, camera behavior, cuts, or request duration |
| [Reference relationships](craft/generated-dependencies.md) | deciding which images or Takes should depend on which references |
diff --git a/skills/hypit/references/production/authoring.md b/skills/hypit/references/production/authoring.md
index c68b11c7..0db76f59 100644
--- a/skills/hypit/references/production/authoring.md
+++ b/skills/hypit/references/production/authoring.md
@@ -28,6 +28,7 @@ Bring the relevant directing knowledge into those decisions: use
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,
[Caption](../playbooks/craft/captions.md) for speech-linked text, and
diff --git a/skills/hypit/references/production/builds.md b/skills/hypit/references/production/builds.md
index f4107d63..d06009db 100644
--- a/skills/hypit/references/production/builds.md
+++ b/skills/hypit/references/production/builds.md
@@ -43,8 +43,9 @@ work. The next attempt's choices belong in that Run; the earlier Build retains i
When a Provider task-submission request times out without a task ID or another usable receipt,
the Result can establish the request failure and absence of a receipt, while the remote outcome remains
-unknown. A later submission is a new Build and a new spending decision; proceed under the user's
-authority and select any Outputs already available from the earlier attempt in its Run.
+unknown. A later submission is a new Build. Assess its paid requests against the
+[agreed scope and cost](#work-within-the-agreed-paid-scope), and select any Outputs already available
+from the earlier attempt in its Run.
When a usable receipt does exist and gives access to a generated asset, the Agent can retrieve that
asset as an ordinary project file and select it with `file` and `satisfy` in the new Run. This supplies
@@ -80,17 +81,21 @@ hypit pricing path/to/build.svrun
```
`pricing` is an explicit read-only network operation. It creates no Build and submits no generation.
-It places each Need beside the current documents or page supplied by its selected Endpoint. Providers
-may expose a narrow model record or a broader catalogue; Hypit does not impose a common price-table
-shape or calculate a total. Use the Need's authored duration, resolution, count, or other billing facts
-to calculate and explain the relevant cost. Missing or broad pricing material is uncertainty to report,
-not a system prohibition on an otherwise authorized Build.
-
-The default human view groups matching Needs and keeps Provider documents folded to their source URLs.
-Use `--json` when you need the original documents for calculation, or `--verbose` to inspect them in the
-terminal. A mixed production naturally has separate image, video, voice, alignment, and local-processing
-entries. Read each relevant entry against its own Need, then explain the production's expected cost in
-ordinary language.
+The default report groups matching requests by their selected Endpoint and pricing material, showing
+known parameters, request counts, and the Provider's rate summary or document with its source URL. Explicit
+no-charge work is summarized in one count. Missing pricing declarations and failed queries stay
+visible as uncertainty; a declared price page remains useful when the Provider supplies no document.
+
+Use the stated units and conditions together with authored duration, resolution, count, or other
+billing facts to calculate and explain the expected cost. Providers may publish several price tiers
+for one model; match the request to the applicable conditions. A future audio input may not have a
+known duration yet. Use its per-audio-second rate with an explicitly estimated length from the
+production plan, keeping that estimate distinct from measured usage. Hypit itself calculates no total.
+
+`--json` puts each group's `requests` beside its `pricingDocuments`, retaining the Provider's original
+data. Both views include all pricing groups by default. `--limit <count>` shortens only the human
+view; `--verbose` shows original documents and the no-charge work. Read the relevant groups and explain
+the expected cost of the described work, the account that would pay and any material uncertainty.
Read the remaining Needs against this change. A Caption or MG-only revision should keep its existing
media generation satisfied; replacing selected B-roll should leave the unchanged performance satisfied.
@@ -98,10 +103,34 @@ Rendering and other required processing may still appear as Needs. Explain each
from the user's goal or an explicit generation decision. If a request appears because a Candidate was
lost or never selected, repair the Run and plan again before asking to spend or submitting work.
-Before new paid work, tell the user which requests and Provider Endpoints the plan selected and report
-the available calculation or link its Provider source. Existing explicit authorization for that described work is sufficient; otherwise
-obtain authorization before `build`. Authorization to correct downstream work does not silently extend
-to regenerating unchanged media. Additional paid work outside the authorized scope needs a new decision.
+## Work within the agreed paid scope
+
+Spending authority covers a described piece of work through the selected billing accounts and the
+cost or budget the user accepts. Explain those terms before asking for authorization, using the
+available Provider rates and the work's expected usage. Give an estimate at the precision the current
+plan supports, with material uncertainty visible. Account access and available quota describe what
+can run; the user's agreement establishes what you may spend to make it.
+
+The commission can cover a whole production, including reference transcription, generated media
+and semantic alignment, or just the reference analysis before the user decides to commission the
+video. Early hosted transcription fits either scope. Establish its coverage before invoking
+`hypit transcribe`, which immediately calls the selected Endpoint. For that reference, source
+duration and the Provider's published rates can support the estimate; a production Run need not
+exist yet. Local WhisperX has no hosted Provider call charge. As the creative plan becomes concrete,
+`plan` and `pricing` expose the exact remaining requests for that Run.
+
+Carry covered work forward and keep the user informed. The same agreement can apply across tool
+calls and Builds; a new command is not itself a new authorization request. Ask for a new decision
+when the work expands beyond the agreed scope or cost, or would use an account outside that agreement.
+Use the current plan, available Results and costs already incurred or committed to judge the
+remaining work. Treat estimates as estimates where actual charges are unavailable.
+
+Preserve the user's agreement in [Brief](../creation/brief.md#brief-preserves-user-authority), and
+resume from it alongside the current Run, Results and Progress. Normal composition work carries
+usable generated media forward. A request to revise Caption or MG authorizes that revision;
+additional media generation follows an intentional production choice covered by the paid scope.
+Explain a meaningful change while proceeding when it is already covered; seek the user's decision
+when it changes what they have agreed to fund.
## Submit one durable Build
diff --git a/skills/hypit/references/production/component-sharing.md b/skills/hypit/references/production/component-sharing.md
index d17d4ebb..8b5bfcfe 100644
--- a/skills/hypit/references/production/component-sharing.md
+++ b/skills/hypit/references/production/component-sharing.md
@@ -2,9 +2,14 @@
Read this when someone else needs a project component, Prompt Kit, Model, or Provider.
+Creating a component and distributing it answer different questions. Create the component when the
+work needs its visual role, semantic behavior or interaction. Distribution begins when its owner
+wants another project or person to use the same package. Its component model and ownership stay the
+same across that boundary.
+
## Share the package that owns the component
-A component can begin under the video project's `packages/` directory. Give it an owner-scoped name,
+A component normally begins under the video project's `packages/` directory. Give it an owner-scoped name,
such as `@studio/score-strip`. Sharing it means giving the other project that package's code, assets,
and usage instructions. Neither author nor consumer needs a Hypit repository checkout.
@@ -61,6 +66,48 @@ pnpm add @studio/[email protected]
The project lockfile records the installed dependency tree. Updates are explicit package-manager
operations; Builds use the selected installed code. A missing package is an installation problem.
+## Make a public release discoverable
+
+People can find a public component through its npm page, source repository, or a community link.
+Ordinary package metadata makes those existing discovery surfaces useful. For example, add fields
+like these to the package that already owns the component:
+
+```json
+{
+ "description": "A speech-timed score strip for Hypit videos.",
+ "keywords": ["hypit", "hypit-author-package", "scoreboard"],
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/studio/score-strip.git"
+ },
+ "license": "MIT"
+}
+```
+
+The description and keywords help npm search; they do not define the component ABI. The README should
+show the visual role, a copyable Source import and element example, the package's public outputs, and
+the selected Hypit release used to check it. Include the Surface poster and, when motion or state is
+central to the idea, a short representative clip or animation. The source repository, publisher,
+license and selected release give a recipient the facts needed to choose whether to install it.
+
+After installation, inspect the package's own declarations:
+
+```bash
+hypit vocabulary @studio/score-strip
+```
+
+That output explains the installed release's Surfaces and vocabulary. npm or the selected private
+registry remains the authority for package bytes and versions; the project lockfile records the
+consumer's exact choice.
+
+## Adapt the package under its owner's identity
+
+Ordinary changes to words, media, timing, palette or exposed parameters remain in the consuming
+project's Source and Recipes. When someone changes the reusable mechanics or public behavior, the
+fork can take that owner's package scope and Module identity, subject to the original license. The
+new package is then installed, versioned and imported through the same mechanism as any other shared
+component.
+
## Include what the recipient needs
The package's `files` and `exports` should include its built activation, runtime code, preview assets,
@@ -88,3 +135,10 @@ A Prompt Kit can export an `.svs` Source through ordinary package `exports` with
That reads the selected package data. The same packing, installation, versioning, and file-completeness
rules apply. [Project handoff](../creation/project-files.md#hand-over-an-editable-production) explains
sharing the Sources, Runs, assets and Results needed to continue a video on another machine.
+
+## Official Distribution ownership is a separate decision
+
+A package maintained in the official Hypit Distribution becomes part of Hypit's product and release
+surface. A proposal for that ownership begins with an issue that explains the shared production need
+and maintenance boundary. Community reuse remains under the package owner's own releases, independent
+of that product decision.