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.

refactor: stop the playground reading stylesheets, and knowing Film

rpone351b8ad63f1b
diff --git a/docs/guide/playground.md b/docs/guide/playground.md
index 1321ae04..6d0fe19c 100644
--- a/docs/guide/playground.md
+++ b/docs/guide/playground.md
@@ -21,78 +21,39 @@ no credentials, no local services.
| Control | What it does |
|---|---|
| Component list | Every module that can put pixels on a frame |
-| W / H / fps / sec | The canvas and the frame domain |
-| Appearance from a stylesheet | Adopt a `.svs` Film Recipe's background |
+| W / H / fps / sec / bg | The canvas, the frame domain and the clear colour |
| Input forms | One per input the component takes |
| Scrubber | Frame-exact; the counter shows `frame / last` |
-The preview uses the installed modules' real Producer handlers. For example,
-Fine Caption, Media Track, Screen Overlay, Speech Basis and Typography Track
-all lower to `VisualTrack`, then `compileHyperframesDocument` produces the same
-document a Build would render.
+The preview runs the installed modules' real Producer handlers and compiles the
+same document a Build would render.
-## It lists nothing
+The list and the forms are read from the manifests, so a module that declares a
+Producer emitting a `VisualTrack` appears on its own.
-The playground has no list of components. It reads the manifests and offers
-every module that declares a Producer whose output type is `VisualTrack`. Add a
-module that emits one and it appears; stop emitting one and it disappears.
+## Controls
-Everything else is read the same way:
-
-| Question | Answered by |
-|---|---|
-| What a component needs | that Producer's `inputs` |
-| What shape each input has | the declaring module's `TypeDeclaration.schema` |
-| What to start from | that type's `TypeDeclaration.default` |
-| What a control looks like | `ValueSchema.format` |
-
-So a caption's `mode` is a dropdown because its schema declares an `enum`, and
-its `display` is a text area because the field is `format: "multiline"`. Neither
-is configured here.
-
-## Formats
-
-`format` is how a module says what a value means when its type alone is
-ambiguous — a colour and a font family are both strings.
+A module annotates a field with `format` to say what the value means:
| Format | Control |
|---|---|
-| `color` | Swatch beside a text box. The text is authoritative, because `#RRGGBBAA` carries alpha a swatch cannot. |
+| `color` | Swatch beside a text box. Type the value to set alpha: `#RRGGBBAA`. |
| `unit-fraction` | Slider plus a number box |
| `multiline` | Text area |
| `digest` | File picker |
| `duration` | Number box, in seconds |
-`color` and `digest` have an exact shape, so `validateStoredValue` enforces
-them. The others describe without narrowing.
-
## Media
-A `format: "digest"` field takes a file. The playground hashes it with SHA-256
-and registers a real content-addressed identity, because a compiled document
-cross-checks every Artifact reference and would reject a stub.
-
-Modules that draw supplied footage — B-roll, speaker footage — therefore have no
-default: a module has no bytes to point at, so it says nothing rather than
-inventing a digest. Until you choose a file those components draw nothing, which
-is a state to pass through and not an error.
-
-## Stylesheets
-
-Choosing a `.svs` file reads **only its Film Recipe**, and only for Film
-appearance. Point it at `examples/talking-film-golden/studio.svs` and the
-preview adopts that Recipe's background. Canvas dimensions and time remain
-explicit preview-environment controls.
-
-Nothing else in the sheet is read. What a component looks like comes from the
-module that owns it, not from a stylesheet the playground happened to open.
+A `format: "digest"` field takes a file, hashed as you pick it. Components that
+draw supplied footage — B-roll, speaker footage — draw nothing until you choose
+one.
## When something is wrong
-Nothing in the playground validates. The modules' own `seal` and `assert`
-functions are the judge, because they are what a real Build runs. A rejected
-value shows the compiler's own message under the canvas and leaves the last good
-frame on screen, so you can read the error and the picture together.
+A rejected value shows the compiler's own message under the canvas and leaves
+the last good frame on screen, so you can read the error and the picture
+together.
## Known divergences from a real render
@@ -100,7 +61,7 @@ frame on screen, so you can read the error and the picture together.
`FontArtifactRef` path with hashed `@font-face` families is not exercised.
- Audio tracks are not played.
- A `ProgramSpace` input is filled from the canvas controls rather than offered
- in a form, so there is only one place to change the frame domain.
+ in a form.
See [`tools/playground/README.md`](https://github.com/cashdiffusion/svml/blob/main/tools/playground/README.md)
for how the timeline shim works and what a module must declare to be
diff --git a/docs/zh/guide/playground.md b/docs/zh/guide/playground.md
index bf6beafa..fc23a883 100644
--- a/docs/zh/guide/playground.md
+++ b/docs/zh/guide/playground.md
@@ -19,73 +19,41 @@ pnpm playground
| 控件 | 作用 |
|---|---|
| 组件下拉 | 所有能在画面上产生像素的模块 |
-| W / H / fps / sec | 画布与帧域 |
-| Appearance from a stylesheet | 采用某个 `.svs` Film Recipe 的背景 |
+| W / H / fps / sec / bg | 画布、帧域与清除颜色 |
| 输入表单 | 组件每个输入各一份 |
| 刻度条 | 帧精确,计数显示为 `当前帧 / 末帧` |
-预览运行的是已安装模块真正的 Producer handler。例如 Fine Caption、Media Track、
-Screen Overlay、Speech Basis 和 Typography Track 都会降低为 `VisualTrack`,再由
-`compileHyperframesDocument` 产出与 Build 相同的文档。
+预览运行的是已安装模块真正的 Producer handler,编译出的文档与 Build 渲染的是同一份。
-## 它不维护任何清单
+下拉与表单都读自各个 manifest,所以只要模块声明了「输出 `VisualTrack` 的 Producer」,它自己就会出现。
-Playground 里没有组件列表。它读取各 manifest,把所有声明了「输出 `VisualTrack` 的 Producer」的模块
-列出来。新增这样的模块,它自己会出现;不再输出,它自己会消失。
+## 控件
-其余信息同样是读出来的:
-
-| 问题 | 来源 |
-|---|---|
-| 组件需要什么 | 该 Producer 的 `inputs` |
-| 每个输入什么形状 | 声明方的 `TypeDeclaration.schema` |
-| 从什么值开始 | 该类型的 `TypeDeclaration.default` |
-| 控件长什么样 | `ValueSchema.format` |
-
-所以字幕的 `mode` 是下拉框,因为它的 schema 声明了 `enum`;`display` 是多行文本框,因为该字段是
-`format: "multiline"`。这两者都不在 Playground 里配置。
-
-## format
-
-当类型本身不足以表达含义时,模块用 `format` 说明——颜色和字体名同样都是字符串。
+模块用 `format` 标注一个字段,说明它的值是什么:
| format | 控件 |
|---|---|
-| `color` | 色板配文本框。以文本框为准,因为 `#RRGGBBAA` 带的 alpha 色板表达不了 |
+| `color` | 色板配文本框。要带 alpha 就在文本框里写 `#RRGGBBAA` |
| `unit-fraction` | 滑块加数字框 |
| `multiline` | 多行文本框 |
| `digest` | 文件选择 |
| `duration` | 数字框,单位秒 |
-`color` 和 `digest` 有确切形状,由 `validateStoredValue` 校验。其余只描述,不收窄。
-
## 媒体
-`format: "digest"` 的字段接受一个文件。Playground 用 SHA-256 计算并注册真实的内容寻址标识——
-编译产出的文档会交叉校验每一个 Artifact 引用,占位值会被拒绝。
-
-因此绘制外部素材的模块(B-roll、说话人画面)**没有默认值**:模块手里没有那些字节,与其编造一个
-digest,不如什么都不说。在你选择文件之前这些组件不画任何东西,这是一个可以经过的状态,不是错误。
-
-## 样式表
-
-选择 `.svs` 文件**只读其中的 Film Recipe**,且只用于 Film 外观。指向
-`examples/talking-film-golden/studio.svs`,预览会采用该 Recipe 的背景色;画布尺寸与时间仍由
-预览环境的显式控件决定。
-
-表里其余内容一概不读。组件长什么样由拥有它的模块决定,而不是由 Playground 恰好打开的某张样式表决定。
+`format: "digest"` 的字段接受一个文件,选中即计算哈希。绘制外部素材的组件(B-roll、说话人画面)
+在你选择文件之前不画任何东西。
## 出错时
-Playground 自身不做任何校验。裁判是各模块自己的 `seal` 与 `assert` 函数——它们正是真实 Build 会跑的
-东西。被拒绝的值会把编译器原本的报错显示在画布下方,并保留上一帧正确画面,让你能同时看到错误和图像。
+被拒绝的值会把编译器原本的报错显示在画布下方,并保留上一帧正确画面,让你能同时看到错误和图像。
## 与真实渲染的已知偏差
- 字体降级为普通 CSS `font-family` 字符串,不会走生产环境中带哈希 `@font-face` 的
`FontArtifactRef` 路径。
- 不播放音频轨。
-- `ProgramSpace` 输入由画布控件填充而非出现在表单里,使帧域只有一处可改。
+- `ProgramSpace` 输入由画布控件填充,不出现在表单里。
时间线 shim 的原理、以及一个模块需要声明什么才能被预览,见
[`tools/playground/README.md`](https://github.com/cashdiffusion/svml/blob/main/tools/playground/README.md)。
diff --git a/tools/playground/README.md b/tools/playground/README.md
index d692d577..60105962 100644
--- a/tools/playground/README.md
+++ b/tools/playground/README.md
@@ -6,17 +6,16 @@ Look at a visual component without running a Build.
pnpm playground
```
-Pick a producer, fill in its inputs, and it renders on a canvas of the size you
-choose. Choose a `.svs` stylesheet and its Film Recipe fills in Film appearance;
-canvas size and time stay explicit preview-environment controls.
+Pick a producer, fill in its inputs, and it renders on a canvas whose size,
+frame rate, duration and background you choose.
[The guide page](../../docs/guide/playground.md) covers using it. This file
covers how it works.
-## It lists nothing
+## Where everything comes from
-There is no registry here, and no per-component code. Everything comes from
-what the compiler already declares about itself:
+There is no registry here and no per-component code. Each answer is read at run
+time:
| Question | Answered by |
|---|---|
@@ -27,13 +26,13 @@ what the compiler already declares about itself:
| What to start from | `TypeDeclaration.default`, given by the module that owns the type |
| How to run it | the module's `component.producers[].handler` |
-A module that gains a visual Producer appears here on its own. One that loses
-it disappears. Neither requires editing anything in this directory.
+A module that gains a visual Producer appears here on its own; one that loses it
+disappears. Neither requires editing anything in this directory.
-Nothing here validates, either: `validateStoredValue` and the modules' own
-`seal*` and `assert*` functions are the judge, because they are what a real
-Build runs. A rejected value shows the compiler's own message beside the form
-and leaves the last good frame up.
+Nothing here validates. `validateStoredValue` and the modules' own `seal*` and
+`assert*` functions are the judge, since they are what a real Build runs. A
+rejected value shows the compiler's own message beside the form and leaves the
+last good frame up.
## Two things a Build supplies that the document does not
@@ -53,17 +52,16 @@ self-sufficient — a real render supplies a producer for the rest. The shim in
Nothing to add here. In the module: declare a Producer that outputs a
`VisualTrack`, give each input type a `schema`, and give it a `default` where
-you honestly can. A type carrying content-addressed media has no default — say
-nothing rather than inventing a digest, and the playground will ask the operator
-for a file instead.
+one exists. A type carrying content-addressed media has none, and the playground
+asks the operator for a file instead.
-Annotate a field with `format` where its type alone is ambiguous: a colour and
-a font family are both strings, and only the module knows which is which.
+Annotate a field with `format` where its type alone is ambiguous — a colour and
+a font family are both strings.
## Known divergences from a real render
- Fonts lower to a plain CSS `font-family` string. The production
`FontArtifactRef` path with hashed `@font-face` families is not exercised.
- Audio tracks are not played.
-- The frame domain is the shell's, not the form's: a `ProgramSpace` input is
- filled from the canvas controls, so there is only one place to change it.
+- A `ProgramSpace` input is filled from the canvas controls rather than offered
+ in a form.
diff --git a/tools/playground/src/svml.ts b/tools/playground/src/svml.ts
index 5cf80839..a05d9a46 100644
--- a/tools/playground/src/svml.ts
+++ b/tools/playground/src/svml.ts
@@ -41,10 +41,3 @@ export type {
} from "@narratage/protocol";
export type { MediaArtifactRef } from "@narratage/media";
-
-// Stylesheets are read to fill a form, never to decide what a component is.
-export { parseSvs } from "@narratage/svs";
-export type { SvsRecipe } from "@narratage/svs";
-export { maskSourceHeader, parseSourceHeader } from "@narratage/source";
-
-export { defaultFilmProgram, filmAppearanceFromRecipe, filmRecipeKeys } from "@narratage/film";
diff --git a/tools/playground/src/ui/shell.ts b/tools/playground/src/ui/shell.ts
index b3dd26da..b0f9cc2c 100644
--- a/tools/playground/src/ui/shell.ts
+++ b/tools/playground/src/ui/shell.ts
@@ -3,13 +3,7 @@ import { workspacePreviewProducers } from "../discovery/workspace.js";
import { renderPreview } from "../preview/render.js";
import {
defaultCanvasSpace,
- defaultFilmProgram,
defaultProgramSpace,
- filmAppearanceFromRecipe,
- filmRecipeKeys,
- maskSourceHeader,
- parseSourceHeader,
- parseSvs,
sealProgramSpace,
} from "../svml.js";
import type { CanonicalValue, ProgramSpace, Track } from "../svml.js";
@@ -33,14 +27,11 @@ const CSS = `
.section { color: var(--accent); font-size: 11px; margin: 15px 0 4px; }
.section:first-child { margin-top: 0; }
.module { color: var(--muted); font-size: 11px; font-family: ui-monospace, monospace; margin-top: 4px; }
-.sheet-note { color: var(--muted); font-size: 12px; margin-top: 7px; }
-.sheet-note b { color: var(--accent); font-weight: 500; }
-.sheet-file { font-size: 11px; color: var(--muted); max-width: 100%; }
-.sheet-file::file-selector-button {
- border: 1px solid var(--line); border-radius: 5px; background: #1c1c21;
- color: var(--text); font: inherit; font-size: 11px; padding: 3px 9px; margin-right: 7px; cursor: pointer;
+.hint { color: var(--muted); font-size: 12px; margin-top: 7px; }
+.rail-canvas input[type=color] {
+ width: 100%; height: 24px; padding: 0; border: 1px solid var(--line);
+ background: none; border-radius: 5px;
}
-.sheet-file::file-selector-button:hover { border-color: #3a3a42; }
${FORM_CSS}
`;
@@ -61,6 +52,7 @@ export async function mountShell(root: HTMLElement): Promise<void> {
<span>H</span><input type="number" data-height min="16" step="2" />
<span>fps</span><input type="number" data-fps min="1" step="1" />
<span>sec</span><input type="number" data-duration min="0.1" step="0.1" />
+ <span>bg</span><input type="color" data-background />
</div>
</div>
<div class="rail-body"></div>
@@ -73,6 +65,7 @@ export async function mountShell(root: HTMLElement): Promise<void> {
const heightInput = rail.querySelector<HTMLInputElement>("[data-height]")!;
const fpsInput = rail.querySelector<HTMLInputElement>("[data-fps]")!;
const durationInput = rail.querySelector<HTMLInputElement>("[data-duration]")!;
+ const backgroundInput = rail.querySelector<HTMLInputElement>("[data-background]")!;
const stage = createStage();
root.append(rail, stage.element);
@@ -89,16 +82,16 @@ export async function mountShell(root: HTMLElement): Promise<void> {
picker.append(option);
}
- // Spatial owns geometry, Film owns appearance and ProgramSpace owns time.
- // The preview starts from those three package-owned values instead of a
- // second playground-specific model of a frame.
+ // Spatial owns geometry and ProgramSpace owns time, so the preview starts
+ // from those package-owned values rather than a second playground model of a
+ // frame. The clear colour belongs to a Composition, and a preview assembles
+ // none, so it is a stage control the operator sets like the others.
const canvasSpace = defaultCanvasSpace();
- const film = defaultFilmProgram();
const defaultSpace = defaultProgramSpace();
const canvas = {
width: canvasSpace.widthPx,
height: canvasSpace.heightPx,
- clearColor: film.clearColor,
+ clearColor: "#09090b",
};
const space = {
fps: defaultSpace.frameRate.numerator / defaultSpace.frameRate.denominator,
@@ -175,51 +168,6 @@ export async function mountShell(root: HTMLElement): Promise<void> {
}
}
- const note = document.createElement("div");
- note.className = "sheet-note";
-
- /**
- * Reads a chosen stylesheet for Film appearance.
- *
- * Geometry and time are graph inputs, not style. A Film Recipe may therefore
- * change only the Composition background; component Recipes remain owned by
- * their own modules.
- */
- function loadSheet(file: File): void {
- void file.text().then((source) => {
- const header = parseSourceHeader(file.name, source);
- if (!header.using.startsWith("@narratage/svs@")) {
- throw new Error(`${file.name} is a ${header.using} source, not a stylesheet.`);
- }
- const sheet = parseSvs(file.name, maskSourceHeader(source, header));
- const filmShape = [...filmRecipeKeys].sort().join(" ");
- const found = sheet.recipes.find((recipe) =>
- Object.keys(recipe.value.properties).sort().join(" ") === filmShape);
- if (found === undefined) {
- note.textContent = `${file.name} declares no Film Recipe, so the background is unchanged.`;
- return;
- }
- const read = filmAppearanceFromRecipe(found.value.properties);
- canvas.clearColor = read.clearColor;
- note.replaceChildren(document.createTextNode("Background from "));
- const which = document.createElement("b");
- which.textContent = found.value.path;
- note.append(which);
- render();
- }).catch((error: unknown) => {
- note.textContent = error instanceof Error ? error.message : String(error);
- });
- }
-
- const sheetPicker = document.createElement("input");
- sheetPicker.type = "file";
- sheetPicker.accept = ".svs";
- sheetPicker.className = "sheet-file";
- sheetPicker.addEventListener("change", () => {
- const file = sheetPicker.files?.[0];
- if (file !== undefined) loadSheet(file);
- });
-
function section(title: string): HTMLElement {
const element = document.createElement("div");
element.className = "section";
@@ -230,7 +178,7 @@ export async function mountShell(root: HTMLElement): Promise<void> {
function renderRail(): void {
const values = draft(active);
moduleLine.textContent = active.moduleName;
- body.replaceChildren(section("Appearance from a stylesheet"), sheetPicker, note);
+ body.replaceChildren();
for (const input of active.inputs) {
// The shell owns the frame domain; offering it again would be a second
@@ -239,14 +187,14 @@ export async function mountShell(root: HTMLElement): Promise<void> {
body.append(section(input.name));
if (input.schema === undefined) {
const missing = document.createElement("div");
- missing.className = "sheet-note";
+ missing.className = "hint";
missing.textContent = `${input.type.module.name} declares no schema for ${input.type.name}.`;
body.append(missing);
continue;
}
if (values[input.name] === null || values[input.name] === undefined) {
const empty = document.createElement("div");
- empty.className = "sheet-note";
+ empty.className = "hint";
empty.textContent = `${input.type.module.name} offers no default for ${input.type.name}.`;
body.append(empty);
}
@@ -264,6 +212,11 @@ export async function mountShell(root: HTMLElement): Promise<void> {
heightInput.value = String(canvas.height);
fpsInput.value = String(space.fps);
durationInput.value = String(space.durationSec);
+ backgroundInput.value = canvas.clearColor;
+ backgroundInput.addEventListener("input", () => {
+ canvas.clearColor = backgroundInput.value;
+ schedule();
+ });
for (const [input, apply] of [
[widthInput, (n: number) => { canvas.width = n; }],
[heightInput, (n: number) => { canvas.height = n; }],