@aixcut/vibevideo 0.1.0-beta.0 → 0.1.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (26) hide show
  1. package/README.md +35 -5
  2. package/dist/skills/vibevideo/SKILL.md +75 -0
  3. package/dist/skills/vibevideo/assets/pixi/01-kinetic-title.mjs +76 -0
  4. package/dist/skills/vibevideo/assets/pixi/02-flow-map.mjs +76 -0
  5. package/dist/skills/vibevideo/assets/pixi/03-nested-board.mjs +69 -0
  6. package/dist/skills/vibevideo/assets/pixi/04-compact-callout.mjs +40 -0
  7. package/dist/skills/vibevideo/assets/pixi/README.md +11 -0
  8. package/dist/skills/vibevideo/references/authoring.md +160 -0
  9. package/dist/skills/vibevideo/references/editing-and-reload.md +99 -0
  10. package/dist/skills/vibevideo/references/editor-connection.md +44 -0
  11. package/dist/skills/vibevideo/references/examples.md +230 -0
  12. package/dist/skills/vibevideo/references/graphic-workflow.md +167 -0
  13. package/dist/skills/vibevideo/references/hevc-encoder.md +12 -0
  14. package/dist/skills/vibevideo/references/runtime-api.md +211 -0
  15. package/dist/skills/vibevideo/references/validation.md +109 -0
  16. package/dist/skills/vibevideo-cli/SKILL.md +86 -0
  17. package/dist/skills/vibevideo-cli/references/agent-protocol.md +39 -0
  18. package/dist/skills-manifest.json +14 -0
  19. package/dist/studio/assets/{browserAll-wERvpUP9.js → browserAll-0i6gm1iO.js} +1 -1
  20. package/dist/studio/assets/{index-bnkX1rLy.js → index-DqX5Prpj.js} +3 -3
  21. package/dist/studio/assets/{prores-encoder-mediabunny-hm5PQfLy.js → prores-encoder-mediabunny-DjdaA3bm.js} +2 -2
  22. package/dist/studio/assets/{webworkerAll-Baf-n-Bc.js → webworkerAll-Xo9FRLTy.js} +1 -1
  23. package/dist/studio/index.html +1 -1
  24. package/package.json +1 -1
  25. package/src/cli.mjs +30 -3
  26. package/src/skills.mjs +110 -0
@@ -0,0 +1,99 @@
1
+ # 修改、命中与源码替换
2
+
3
+ > 当前 `apps/studio` 使用 nle-video 时间轴,并提供本地 HTML、Three.js 和 PixiJS 图形的宿主命中和场景编辑。使用“打开 → HTML 项目目录”选中源码根目录后,时间轴保存在该目录的 `vibevideo.project.json`;项目入口和已使用依赖保留原路径,外部修改会自动重载。一般素材目录项目仍可用“本地项目目录”打开。
4
+
5
+ ## 选择正确的修改层
6
+
7
+ | 用户要改什么 | 当前路径 | 会改变什么 |
8
+ | --- | --- | --- |
9
+ | 整段图形的位置、宽高、旋转 | 片段布局或普通预览拖动 | 时间轴片段几何 |
10
+ | Three.js 物体的位置 | 选中场景对象后拖动或改位置数值 | 当前片段中该地址的对象 override |
11
+ | PixiJS 显示对象的位置、旋转、缩放、透明度、可见性或文字 | 注册对象与能力后,在选框浮层中调整 | 当前片段中该地址的对象 override |
12
+ | HTML 元素的位置、旋转、缩放 | 直接点选元素,在选框浮层中调整 | 当前片段中该地址的 DOM override |
13
+ | HTML 文案、颜色、字号和透明度 | 选中可编辑 HTML 元素后在浮层中调整 | 当前片段中该地址的 DOM override |
14
+ | 相机位置 | “编辑场景”中的“编辑相机”与位置数值 | 当前片段相机 override |
15
+ | 已绑定的主题色 | 图形颜色控件 | 当前片段的 `props.color`,通过 update 更新 |
16
+ | 文案、形体、内部排版、动画节奏、未暴露的参数 | 修改源码后“替换图形” | 所选片段使用的图形源码 |
17
+
18
+ 选框浮层根据当前对象报告的能力显示旋转、缩放、材质、灯光、镜头或文字控件。它不会自动推断任意渲染器插件或自定义对象的属性;没有在能力契约中声明的字段不能在编辑器里调整。
19
+
20
+ 修改现有作品时先读取原文件、已有 props 的约定及可编辑地址。局部修改沿用原来的视觉方向、片段布局、节点身份和参数键。需要全新信息结构时,可以交付新文件,但说明它是新图形还是原图形的兼容修订。
21
+
22
+ ## 为可编辑元素保留真实对象
23
+
24
+ 需要编辑 Three.js 对象的模块返回实际绘制使用的 `scene` 和 `camera`,并在 mount 中创建持久对象:
25
+
26
+ ```js
27
+ mesh.name = '产品主体';
28
+ mesh.userData.address = 'product-body';
29
+ camera.name = '主相机';
30
+ camera.userData.address = 'main-camera';
31
+ ```
32
+
33
+ `name` 用于用户阅读,显式设置的 `userData.address` 用于稳定身份。按对象语义填写唯一地址,使其不随显示文案、子节点顺序、随机数或运行次数改变。不要依赖 Three.js 的运行时 id/uuid。
34
+
35
+ PixiJS 显示对象使用 `modules.VIBEVIDEO.registerPixiObject(displayObject, { address, name, editable })` 注册。宿主将其显示在场景对象列表中,并用声明的能力呈现属性控件。Pixi 的容器、文字和自定义显示对象都可以注册;只有明确声明为 `text` 的文字对象可编辑文本内容。
36
+
37
+ 普通 HTML/CSS 元素可设置 `data-vibevideo-address="title"` 来指定稳定地址。否则宿主会按 `id` 或元素层级生成地址;自动层级地址会受同级元素增删影响。设置 `data-vibevideo-selectable="false"` 可跳过装饰节点。没有子元素的 HTML 文字节点可编辑文字、文字颜色、背景色、字体、字号、字重、粗体、斜体、下划线、文字阴影、字距、行高、对齐、描边和透明度;SVG 绘制节点可编辑 fill;可选节点还可调整二维变换。混合 DOM 捕获支持常见文字样式、纯色与线性/径向/圆锥渐变背景、圆角、单层文字/盒阴影、二维变换、Canvas filter 与常用 blend mode、SVG、图片、视频和 canvas。CSS mask、伪元素、多层背景/阴影及 3D CSS transform 还未实现浏览器原生级别的像素一致;对最终画面很重要的复杂图形应转成 SVG/Canvas/WebGL,并检查实际导出帧。
38
+
39
+ 宿主依次读取对象的 `address`、`userData.address`、`name`、`type`。唯一的 name/type 会直接作为地址;重复名称会自动补成层级路径,供命中与当前片段编辑使用。自动路径依赖对象层级和同级顺序,源码重排后可能变化。需要跨源码修改保留 overrides 时,仍应给目标设置唯一的 `userData.address`,并避免另一个 `object.address` 覆盖它。
40
+
41
+ 每个可独立编辑的部件保留自己的 Object3D。将整个模型合并成一个 Mesh 后,用户只能编辑整体;InstancedMesh 的多个实例也不会自动获得独立的实例命中和位置编辑。
42
+
43
+ 材质、后处理配置、shader 和效果参数不是可移动实体。Canvas 2D 的 fillRect、fillText 也不是 Three.js 场景节点。若需要用户移动一张文字标签,可用 CanvasTexture + Mesh;若需要移动每个字符,就需要相应的独立对象结构和实际验证。
44
+
45
+ ## 命中与坐标
46
+
47
+ 编辑器将预览点击映射回片段源像素。Three.js Mesh 使用实际几何的 Raycaster;HTML/CSS 元素使用隔离页面中的 DOM 命中;Pixi 使用注册对象的事件命中和 Pixi 世界 bounds。命中结果可提供源像素四角 `quad` 与兼容用的轴对齐 `bounds`;HTML 还会通过 `styleProperties.supported` 列出可编辑样式,选框按实际命中几何绘制,工具栏只显示受支持的属性。普通媒体片段及支持二维缩放的 HTML/Pixi 对象可拖动选框角点调整大小;Three.js 对象通过浮层的缩放数值控件调整。
48
+
49
+ Three.js Mesh 使用实际几何的 Raycaster 求交;空白画布不应通过“离中心最近”选中一个物体。旋转、缩放整个片段以后,内部点击仍通过片段矩阵换算。作者不需要自己添加 pointer 监听、Raycaster、第二个 scene、TransformControls 或选区覆盖层。
50
+
51
+ 灯光等没有三角形的对象,可以从“列出场景对象”中选择。相机通过“编辑相机”选择,不要求点中一个不可见的摄像机模型。
52
+
53
+ 隐藏的节点及隐藏祖先下的节点不会被正常点中。装饰性 Mesh 可设置:
54
+
55
+ ```js
56
+ decoration.userData.selectable = false;
57
+ ```
58
+
59
+ 不要把整个父 Group 标记为不可选,然后又期待其中的 Mesh 能被点击;射线过滤会检查祖先的可选状态。需要选中的部件也应在镜头中有足够可点击面积。
60
+
61
+ ## overrides 与动画的关系
62
+
63
+ 宿主先求值作者动画,再应用编辑器修改,最后 draw。作者不要在 draw 内重新写入位置或相机方向。
64
+
65
+ Three.js 对象位置 override 是轴值替换,不是每帧动画结果上的增量。例如动画给出 `x = sin(timeSeconds)`,用户把 X 改为 `0.5` 后,后续每帧的 X 都为 `0.5`;未被修改的 Y/Z 仍可继续由动画驱动。HTML 元素的二维位置 override 是相对作者布局的像素偏移;旋转、缩放和样式修改会在作者每次 render 后应用。
66
+
67
+ 对动画容器和编辑目标有不同需求时,用明确的父子结构。例如外层 Group 负责整体循环,内层 Mesh 是用户移动的主体。给编辑目标设置清楚的名称和地址,并说明移动它会影响哪个坐标系。
68
+
69
+ XYZ 平移使用对象父坐标系的投影轴。不要用屏幕水平位移直接修改世界 X 来代替宿主的手柄实现。片段旋转也不应改变内部对象的数值或地址。
70
+
71
+ 相机修改属于当前片段的相机状态;作者在 render 中可以求值原始镜头,宿主在 draw 前再应用用户修改。需要一个固定的观察目标时,在 mount 设置 lookAt;不要在 draw 再次重置。
72
+
73
+ ## 参数修订
74
+
75
+ 保持已交付参数键的意义。例如现有作品用 `color` 控制主材质,修订后仍让同一键控制同一视觉角色。重命名参数时说明迁移方式,不能悄悄用新的硬编码值覆盖现有用户设置。
76
+
77
+ 当前 UI 只有颜色控件。文案、字体、速度等参数即使在源码中实现,也需要明确的 update 调用方才可调整;它们不会从代码注释或参数数组中自动成为 UI 控件。
78
+
79
+ 改参数以后检查明显不同的输出。仅观察 props 值、控件文本或 update 返回成功不足以证明材质、纹理和画面已更新。
80
+
81
+ ## 源码替换与保留修改
82
+
83
+ 1. 读取并修改当前源文件,保留同一对象的地址和参数键。
84
+ 2. 在已打开的 HTML 项目目录中直接修改 HTML、模块、样式或被引用的资源;Studio 会自动重载素材并刷新当前预览。单文件素材使用当前界面提供的导入/替换流程;没有该操作时,不要虚构未公开的 agent 或网络接口。
85
+ 3. 新实例会用已有 props 和当前片段 overrides 完成加载与首帧验证,再替换旧实例。
86
+ 4. 检查源代码确实变化,同时已有位置、相机和颜色修改仍然成立。
87
+ 5. 某地址不再存在或地址重复时,界面应报告失效;不要给另一个无关对象换上旧地址来隐藏报错。
88
+
89
+ 源默认值只在没有对应覆盖值时生效。更改源码中的默认颜色,不会覆盖用户已设置的 `props.color`;更改某物体默认位置,也可能被它的既有位置 override 覆盖。先确定用户要保留还是清除既有修改,别通过换地址意外丢失编辑结果。
90
+
91
+ 多个片段引用相同源码时各自独立。当前“替换图形”只更新选中的片段,没有项目级共享素材批量更新服务。
92
+
93
+ 若替换失败,当前实现保留原实例、原画面和编辑状态,并显示错误。排查新文件的 mount、update、render 与资源,不反复导入重复片段来绕开错误。运行时加载失败的已有片段可以“重试加载”。
94
+
95
+ ## 编辑结束与状态范围
96
+
97
+ Escape、“完成场景编辑”或切换到另一个片段会退出内部模式并清理场景选择。取消拖动应还原原状态;不能把中间拖动值当作新源码默认值保存。
98
+
99
+ 编辑器的对象和相机修改保存在时间轴片段 overrides 中,不会回写原始 `.html` / `.mjs`。项目文件夹打开时,这些修改随 `vibevideo.project.json` 保存;外部改动源码会保留仍然有效的稳定地址 overrides。某地址消失或重复时,不要把旧修改转给其他对象。
@@ -0,0 +1,44 @@
1
+ # Local Studio and project workflow
2
+
3
+ Use the installed npm CLI; users do not need this source repository:
4
+
5
+ ```sh
6
+ npx @aixcut/vibevideo@beta init ./my-video --no-open --json
7
+ # Resume instead of creating a second project:
8
+ npx @aixcut/vibevideo@beta open ./my-video --no-open --json
9
+ ```
10
+
11
+ Keep the process alive using the host's persistent terminal capability. Open the
12
+ printed `url` in Chrome/Edge, retaining `?agent=1`. Save the returned `session`
13
+ path, then check `agent status --session ...` until `connected` is true. Project
14
+ loading may precede the connection. The adjacent CLI Skill explains the complete
15
+ [connection and command workflow](../../vibevideo-cli/SKILL.md).
16
+
17
+ ## Source and media
18
+
19
+ For a self-contained graphic, use `agent import --file ./title.mjs --session ...`.
20
+ It returns a new clip and asset ID. The project manifest maps that asset ID to
21
+ its saved path under `assets/`. Later edits to that saved source are watched;
22
+ editing the original pre-import file does not change the copied asset. Replacing
23
+ an existing clip uses an import JSON command with its existing `clipId`.
24
+
25
+ For a multi-file HTML source project, use Studio's **打开 → HTML 项目目录** and
26
+ select the directory containing its entry. This picker requires browser directory
27
+ support and a user gesture. For video, audio and images, use **添加素材** rather
28
+ than the graphic-only agent import. The CLI-selected project directory is
29
+ accessed through the local server and autosaves timeline and media changes.
30
+
31
+ The **保存** action downloads a portable `.vibevideo` project. This differs from
32
+ the CLI-selected folder's automatic `vibevideo.project.json` and `assets/` writes.
33
+ Keep user-authored files and overrides when reopening or replacing source.
34
+
35
+ ## Validation and export
36
+
37
+ Observe actual preview frames and inspect selection/edit persistence. A command
38
+ result or a source file on disk does not prove visual correctness. Use Studio's
39
+ **导出视频** dialog for the final file, then verify duration, media streams and
40
+ sample decoded frames. Available formats/codecs depend on the installed build,
41
+ browser and hardware. There is no CLI render or cloud rendering endpoint.
42
+
43
+ If browser automation is unavailable, deliver the source/project and describe
44
+ which preview, editing and export checks remain unverified.
@@ -0,0 +1,230 @@
1
+ # 完整示例与制作模式
2
+
3
+ 下面前两个 JavaScript 代码块分别是完整的 `.mjs` 入口,可以单独保存并通过“导入素材”加载。它们展示不同能力,不能直接拼接成一个包含多个默认导出的模块。
4
+
5
+ ## PixiJS 场景案例
6
+
7
+ PixiJS 案例拆分为独立文件,保证每个案例都能直接导入,也便于逐个检查:
8
+
9
+ | 案例 | 文件 | 重点验证 |
10
+ | --- | --- | --- |
11
+ | 动态标题 | [`01-kinetic-title.mjs`](../assets/pixi/01-kinetic-title.mjs) | `Text` 内容、位置、旋转、比例、透明度和可见性能力;淡入、下划线展开和稳定文字覆盖 |
12
+ | 流程图 | [`02-flow-map.mjs`](../assets/pixi/02-flow-map.mjs) | 三个独立命中目标、场景列表语义名称、注册子对象与确定性进度标记 |
13
+ | 嵌套卡片 | [`03-nested-board.mjs`](../assets/pixi/03-nested-board.mjs) | 注册父容器和子行、父坐标变换、单行编辑以及 siblings 不互相污染 |
14
+
15
+ 按 [`案例说明`](../assets/pixi/README.md) 导入 Studio。每个案例都应检查首帧与停留帧;选中对象后拖动一次,再前后 seek,确认值仍作用于同一个地址。对象列表和浮层控件应匹配案例源码声明的 `editable` 数组。测试 renderer、静态截图和源码编译不能代替在实际 Pixi 浏览器 renderer 中检查画面和命中。
16
+
17
+ ## Canvas 文字与简单数据图形
18
+
19
+ 这个例子有透明背景、按真实文字宽度换行、入场和退场、基于本地时间的进度条,以及实际生效的 color 更新。`title` 是源码/调用方参数,当前 UI 不会自动生成标题输入框。它支持整段片段布局,不提供内部文字或矩形的场景命中。
20
+
21
+ ```js
22
+ export default function mount({ root, props, viewport }) {
23
+ const canvas = document.createElement('canvas');
24
+ canvas.width = viewport.width;
25
+ canvas.height = viewport.height;
26
+ root.appendChild(canvas);
27
+ const context = canvas.getContext('2d');
28
+ if (!context) {
29
+ canvas.remove();
30
+ throw new Error('无法创建文字画布');
31
+ }
32
+
33
+ const defaults = { title: '用画面解释变化', color: '#3db7ff' };
34
+ let values = { ...defaults, ...props };
35
+ let lines = [];
36
+ let fontSize = 40;
37
+ let state = { opacity: 0, rise: 20, amount: 0 };
38
+
39
+ function wrap(text, width) {
40
+ const output = [];
41
+ for (const paragraph of text.split('\n')) {
42
+ let line = '';
43
+ for (const character of Array.from(paragraph)) {
44
+ if (line && context.measureText(line + character).width > width) {
45
+ output.push(line);
46
+ line = '';
47
+ }
48
+ line += character;
49
+ }
50
+ output.push(line);
51
+ }
52
+ return output;
53
+ }
54
+
55
+ function layout() {
56
+ fontSize = 40;
57
+ do {
58
+ context.font = `600 ${fontSize}px sans-serif`;
59
+ lines = wrap(String(values.title ?? ''), 544);
60
+ if (lines.length * fontSize * 1.3 <= 160 || fontSize <= 20) break;
61
+ fontSize -= 2;
62
+ } while (true);
63
+ if (lines.length * fontSize * 1.3 > 160) {
64
+ throw new Error('标题过长,请缩短文字或重新安排版式');
65
+ }
66
+ }
67
+ try {
68
+ layout();
69
+ } catch (error) {
70
+ canvas.remove();
71
+ throw error;
72
+ }
73
+
74
+ return {
75
+ update({ props: next }) {
76
+ values = { ...defaults, ...next };
77
+ layout();
78
+ },
79
+ render({ timeSeconds, progress }) {
80
+ const enter = Math.min(1, Math.max(0, timeSeconds / 0.35));
81
+ const exit = Math.min(1, Math.max(0, (1 - progress) / 0.1));
82
+ state = { opacity: enter * exit, rise: 20 * (1 - enter), amount: progress };
83
+ },
84
+ draw() {
85
+ context.clearRect(0, 0, canvas.width, canvas.height);
86
+ context.save();
87
+ context.scale(canvas.width / 640, canvas.height / 360);
88
+ context.globalAlpha = state.opacity;
89
+ context.translate(48, 42 + state.rise);
90
+ context.font = `600 ${fontSize}px sans-serif`;
91
+ context.textBaseline = 'top';
92
+ context.fillStyle = String(values.color ?? defaults.color);
93
+ lines.forEach((line, index) => context.fillText(line, 0, index * fontSize * 1.3));
94
+ context.fillRect(0, 240, 544 * state.amount, 8);
95
+ context.restore();
96
+ },
97
+ dispose() { canvas.remove(); },
98
+ };
99
+ }
100
+ ```
101
+
102
+ 系统 sans-serif 仅作为可运行示例。需要指定字体或跨机器一致排版时,在 mount 中完成实际字体文件的加载,再执行 layout,参考下方的字体模式。句子按词、CJK 禁则或复杂书写系统排版时,替换这个简单的逐字符换行器,并检查真实文案。
103
+
104
+ ## GSAP 外部时钟与可编辑场景
105
+
106
+ 这个例子把暂停的 GSAP timeline 用作时间函数。动画只修改普通 motion 对象;每次 render 都向 Three.js 对象显式写值,因此宿主恢复基线或重复请求同一时间时,不依赖 GSAP 是否跳过相同时间的内部赋值。
107
+
108
+ ```js
109
+ export default function mount({ root, props, viewport, modules }) {
110
+ const { THREE, gsap } = modules;
111
+ const renderer = new THREE.WebGLRenderer({ alpha: true, antialias: true });
112
+ renderer.setPixelRatio(1);
113
+ renderer.setSize(viewport.width, viewport.height, false);
114
+ root.appendChild(renderer.domElement);
115
+ const scene = new THREE.Scene();
116
+ const camera = new THREE.PerspectiveCamera(45, viewport.width / viewport.height, 0.1, 100);
117
+ camera.name = '主相机';
118
+ camera.userData.address = 'main-camera';
119
+ camera.position.set(0, 0, 4);
120
+
121
+ const geometry = new THREE.BoxGeometry(1.2, 1.2, 0.4);
122
+ const material = new THREE.MeshBasicMaterial({ color: props.color ?? '#3db7ff' });
123
+ const mesh = new THREE.Mesh(geometry, material);
124
+ mesh.name = '动画主体';
125
+ mesh.userData.address = 'animated-subject';
126
+ scene.add(mesh);
127
+
128
+ const motion = { y: -0.8, scale: 0.8, turn: 0 };
129
+ const sequence = gsap.timeline({ paused: true });
130
+ sequence.fromTo(motion, { y: -0.8, scale: 0.8 }, { y: 0, scale: 1, duration: 0.7, ease: 'power2.out' }, 0);
131
+ sequence.fromTo(motion, { turn: 0 }, { turn: Math.PI * 0.7, duration: 3.3, ease: 'none' }, 0.7);
132
+ gsap.ticker.sleep();
133
+
134
+ return {
135
+ scene,
136
+ camera,
137
+ update({ props: next }) { material.color.set(next.color ?? '#3db7ff'); },
138
+ render({ timeSeconds }) {
139
+ sequence.totalTime(Math.max(0, Math.min(timeSeconds, sequence.duration())), true);
140
+ gsap.ticker.sleep();
141
+ mesh.position.set(0, motion.y, 0);
142
+ mesh.scale.setScalar(motion.scale);
143
+ mesh.rotation.set(0.15, motion.turn, 0);
144
+ },
145
+ draw() { renderer.render(scene, camera); },
146
+ dispose() {
147
+ sequence.kill();
148
+ gsap.ticker.sleep();
149
+ geometry.dispose();
150
+ material.dispose();
151
+ renderer.dispose();
152
+ renderer.domElement.remove();
153
+ },
154
+ };
155
+ }
156
+ ```
157
+
158
+ 测试时按 `0.5 → 2 → 0.5 → 0.5` 求值。用户改 Y 后,该轴会采用位置 override;旋转仍由时间求值。不要在 draw 里再次给 mesh.position 赋值,否则编辑会被覆盖。
159
+
160
+ 当前每个片段使用独立的沙箱运行时,此例的 ticker 操作只作用于自己的图形实例。自行搭建共享 GSAP 的宿主时,需由该宿主统一管理 ticker 所有权。
161
+
162
+ ## 固定图片与文字纹理
163
+
164
+ ### 图片:导入前嵌入,mount 内解码
165
+
166
+ 先在作者环境中读取用户提供的图片,转换为 data URL,并把该值放进交付模块。下面是外部素材准备代码,不是在沙箱中运行的 mount:
167
+
168
+ ```python
169
+ import base64
170
+ from pathlib import Path
171
+
172
+ image = Path('logo.png')
173
+ data_url = 'data:image/png;base64,' + base64.b64encode(image.read_bytes()).decode('ascii')
174
+ Path('logo-data-url.txt').write_text(data_url)
175
+ ```
176
+
177
+ MIME 类型要对应真实文件格式。把生成的字符串作为模块中的常量或参数默认值;不要把 `logo-data-url.txt` 当成运行时可以相对 import 的资源。
178
+
179
+ 以下是放进自己 mount 内的片段,`imageDataUrl` 是已经嵌入模块的真实图片值:
180
+
181
+ ```js
182
+ const texture = await new THREE.TextureLoader().loadAsync(imageDataUrl);
183
+ texture.colorSpace = THREE.SRGBColorSpace;
184
+ const image = texture.image;
185
+ const geometry = new THREE.PlaneGeometry(2, 2 * image.height / image.width);
186
+ const material = new THREE.MeshBasicMaterial({ map: texture, transparent: true });
187
+ const logo = new THREE.Mesh(geometry, material);
188
+ logo.name = '品牌标识';
189
+ logo.userData.address = 'brand-logo';
190
+ scene.add(logo);
191
+ ```
192
+
193
+ 相应 mount 必须是 async,返回 scene、camera、同步 render、独立 draw 和 dispose。dispose 释放纹理、几何、材质和 renderer;加载失败也释放先前创建的资源。原图片的透明边缘和宽高比必须保留,不能只验证“加载成功”。
194
+
195
+ ### 字体:加载后再排版
196
+
197
+ 下面片段位于 async mount 内。`fontDataUrl` 来自允许使用的实际字体文件;没有完整字形的字体不能修复缺字问题。
198
+
199
+ ```js
200
+ const face = new FontFace('GraphicTitle', `url(${fontDataUrl})`, { weight: '600' });
201
+ await face.load();
202
+ document.fonts.add(face);
203
+ await document.fonts.load('600 40px "GraphicTitle"', titleText);
204
+ ```
205
+
206
+ 再设置 canvas context 的 font,测量真实文字并绘制。dispose 中从 document.fonts 删除此实例添加的 face。不要以浏览器自动 fallback 为依据,宣称使用了指定品牌字体。
207
+
208
+ ### 文字:更新实际纹理
209
+
210
+ 需要 3D 可编辑标签时,文字先画到离屏 canvas,再创建 `THREE.CanvasTexture` 和 Mesh。离屏 canvas 不挂到 root;最终 renderer 的 canvas 才挂到 root。
211
+
212
+ ```js
213
+ const labelCanvas = document.createElement('canvas');
214
+ labelCanvas.width = 512;
215
+ labelCanvas.height = 128;
216
+ const labelContext = labelCanvas.getContext('2d');
217
+ const labelTexture = new THREE.CanvasTexture(labelCanvas);
218
+ labelTexture.colorSpace = THREE.SRGBColorSpace;
219
+ function redrawLabel(text, color) {
220
+ labelContext.clearRect(0, 0, 512, 128);
221
+ labelContext.font = '600 48px sans-serif';
222
+ labelContext.textAlign = 'center';
223
+ labelContext.textBaseline = 'middle';
224
+ labelContext.fillStyle = color;
225
+ labelContext.fillText(text, 256, 64, 480);
226
+ labelTexture.needsUpdate = true;
227
+ }
228
+ ```
229
+
230
+ 在 mount 与 update 中调用 redrawLabel,使用实际的 title/color 参数。纹理对应的标签 Mesh 使用稳定地址。这个模式让用户移动标签整体,不能承诺按字点击或在当前 UI 中自动出现文字输入框。
@@ -0,0 +1,167 @@
1
+ # HTML 动态图形制作
2
+
3
+ 为 Vibevideo Studio 制作可继续修改的动态图形源文件。本文说明制作与可编辑对象契约;启动、Agent 连接和导入方式以 [本地 Studio 工作流](editor-connection.md) 为准。Studio 不提供 AI 对话、云同步或远程渲染。
4
+
5
+ ## 先确认交付形态
6
+
7
+ - **新建图形**:明确内容、画面用途、视觉方向和时序,再编写源文件。
8
+ - **修改已有图形**:先分清片段布局、对象位置、参数、源码四种修改,阅读 [修改、命中与源码替换](editing-and-reload.md)。沿用已确认的视觉方向与稳定地址。
9
+ - **修复预览或交互故障**:阅读 [验证与故障定位](validation.md),先复现错误所在的加载、求值、绘制、命中或导出阶段。
10
+ - **仅交付源码**:保留用户指定的目录和文件,不要求创建项目或导出视频。没有实际加载时,明确说明尚未验证预览。
11
+ - **从其他播放器或框架迁移**:先阅读 [运行时契约](runtime-api.md),转换入口、资源和时钟。普通网页、Remotion 组件或其他框架输出不自动兼容。
12
+
13
+ 编写或改动入口前,完整阅读 [运行时契约](runtime-api.md)。PixiJS 项目还要阅读本文件的能力契约与 [Pixi 示例集](../assets/pixi/README.md)。按需要读取:
14
+
15
+ | 当前工作 | 参考内容 |
16
+ | --- | --- |
17
+ | 视觉方向、分镜、图文排版、透明叠加、素材与字体 | [构图与动画制作](authoring.md) |
18
+ | HTML、Three.js 与 Pixi 场景对象的命中、可编辑能力及重载后的修改保留 | [修改、命中与源码替换](editing-and-reload.md) |
19
+ | Canvas 文字、GSAP 外部时钟、嵌入纹理 | [完整示例与制作模式](examples.md) |
20
+ | 导入、倒序 seek、拖动、导出及错误排查 | [验证与故障定位](validation.md) |
21
+
22
+ ## 当前公共包提供什么
23
+
24
+ | 能力 | 当前边界 |
25
+ | --- | --- |
26
+ | 图形入口 | `.html` / `.htm` 中一个内联 module,或自包含 `.js` / `.mjs` 模块 |
27
+ | 捕获画面 | 捕获 HTML、SVG、图片、视频与 canvas 混合内容;单 canvas 使用原生快照,其余内容通过确定性 Canvas 合成 |
28
+ | 可用模块 | `three`、`gsap`、`pixi.js`;项目内相对模块由项目编译器处理,其他 npm 包、addons、CDN 和远程模块不提供 |
29
+ | 时间求值 | 调用方传入时刻、视口和参数;CSS/Web Animations 在请求帧定位,GSAP/Canvas/WebGL/Pixi 由模块的 `render(time)` 更新 |
30
+ | 内部编辑 | Three.js 返回实际 `scene` / `camera`;PixiJS 通过公开 `VIBEVIDEO` 场景适配器注册稳定对象并声明可编辑能力 |
31
+ | 合成 | 公共 compositor 合成视频帧、图片帧和文字;媒体解码由调用方提供 |
32
+ | 编辑器、导入导出、项目保存 | `apps/studio` 本地导入、项目保存/打开和视觉导出;不依赖在线服务 |
33
+
34
+ HTML 节点、Three.js 场景对象和已注册的 PixiJS 显示对象可通过宿主选取。Canvas 2D 的绘制命令不是独立编辑节点;需要移动文字标签时,可使用 CanvasTexture 与独立 Mesh,或使用 PixiJS 的独立显示对象。
35
+
36
+ ## PixiJS 的编辑能力契约
37
+
38
+ PixiJS 与 HTML 使用同一导入、预览、时间轴、对象列表、选框浮层和导出工作流;对象结构和可编辑字段由各自 renderer 决定。当前适配器支持以下 Pixi 属性:
39
+
40
+ | 注册能力 | Studio 控件 | 当前语义 |
41
+ | --- | --- | --- |
42
+ | `position` | 位置 X / Y | Pixi 父容器坐标系中的逻辑像素 |
43
+ | `rotation` | 旋转 | Z 轴弧度存储、界面显示角度 |
44
+ | `scale` | 缩放 X / Y | 对象局部比例 |
45
+ | `opacity` | 不透明度 | 对象 alpha,范围 0–1 |
46
+ | `visibility` | 显示 / 隐藏 | 对象自身 visible |
47
+ | `text` | 文字 | 仅在对象有字符串 `text` 属性时有效;不改字体、字号或排版 |
48
+
49
+ 只有 `registerPixiObject()` 注册并声明能力的对象可被选择。声明 `text` 的普通 `Container` 不会因此变成文字;需要对象实际具有可读写的字符串 `text`。当前不提供纹理替换、填充颜色、滤镜、shader、mesh 顶点、字体样式或任意插件属性控件。控制项应逐对象变化,不能从 renderer 名称推断。
50
+
51
+ 每个 Pixi mount 创建一个 `Application`,`app.init()` 使用与源视口相同的 `width` / `height`,并设置 `autoStart: false`、`sharedTicker: false`。动画在 `render({ timeSeconds })` 从时间重建;不要使用 ticker 累加或自动循环。先在应用和父级场景组装完毕后注册对象,再创建 `createPixiSceneAdapter()`。适配器会先恢复基线、再接受 overrides、最后显式绘制。适配器负责自身释放;`ownsApplication: true` 时才销毁该应用,而且不会销毁共享纹理源。详见 [运行时契约](runtime-api.md#dispose-释放实例所有权) 与 [Pixi 示例集](../assets/pixi/README.md)。
52
+
53
+ 至少运行一个对象可命中、一个不同能力列表、一个嵌套父子场景的案例。真实画面应在 Studio/Chromium 中检查;适配器单测或合成 renderer 的像素不能代替实际 Pixi renderer 的 WebGL 画面验证。记录实际跑过的入口、采样时刻、命中结果和控制项,不得把源码通过编译写成渲染通过。
54
+
55
+ ## 制作流程
56
+
57
+ ### 1. 整理内容与画面关系
58
+
59
+ 优先使用用户已经确定的文字、数值、品牌、语言、素材和参考画面。只询问会影响成片的缺失信息,例如必须出现的文案或图形要叠在哪个镜头上。
60
+
61
+ 在编写前明确:
62
+
63
+ - 图形要解释什么,观众应首先注意哪个信息。
64
+ - 是透明叠加、局部图形,还是拥有背景的完整画面。
65
+ - 目标比例与自然内容边界。Studio 会自动分析整段动态图形的可见范围;若内容需要按设计稿留白或包含透明边缘,可在源码声明稳定范围,详见 [运行时契约](runtime-api.md#源画面与实际内容范围)。
66
+ - 入场、可读停留、强调与退场的秒数;用户给的绝对时间应换成片段内时间。
67
+ - 哪些元素需要独立点选、哪些值需要以后更换,以及哪些素材保留为外部时间轴片段。
68
+
69
+ 图形时长、视口和项目帧率由集成调用方决定。不得把已删除编辑器的 4 秒、640 × 360 和 30 fps 当作公共宿主的固定限制。
70
+
71
+ ### 2. 确定构图,再设计运动
72
+
73
+ 阅读 [构图与动画制作](authoring.md)。先让停留帧中的信息层级、位置、字重、素材裁切成立,再加动画。沿用用户的参考和已确认设计;局部改色或改文案不重新做视觉方向选择。
74
+
75
+ 研究参考时说明实际借鉴的是排版、形状、材质、空间关系还是运动顺序。只见过静态图时,不声称复现了它的动画。使用用户提供的真实 logo、图片和数据,不用程序化近似图替代必须出现的素材。
76
+
77
+ ### 3. 建立可 seek、可编辑的图形
78
+
79
+ - 在 `mount` 中创建节点、加载资源和建立动画结构。所有异步加载在返回前完成。
80
+ - 在 `render({ timeSeconds, progress, frame })` 中同步求值当前时刻;每次调用都能独立成立。
81
+ - 在 `draw()` 中绘制最终画面,让宿主有机会在求值后、绘制前应用对象和相机修改。
82
+ - 为编辑目标保留稳定对象,设置唯一的 `userData.address`。用户可编辑的形体不要每帧删除再创建。
83
+ - PixiJS 显示对象使用 `modules.VIBEVIDEO.registerPixiObject()` 注册稳定地址、名称和可编辑能力;宿主只为所声明的属性显示编辑控件。
84
+ - 用 `props` 保存参数,在 `update({ props })` 中真正更新材质、文字纹理或其他内容;不要只修改一个未参与绘制的变量。
85
+ - 在 `dispose()` 中释放自己创建的纹理、几何、材质、renderer、动画实例和 DOM 节点。
86
+
87
+ PixiJS 使用同一时间轴、预览、对象列表、选框和属性浮层。通过 `modules.PIXI` 或 `pixi.js` 静态导入使用库,通过 `modules.VIBEVIDEO` 创建场景适配器。应用初始化时关闭自动启动;每次 `render` 从时间参数重建动画状态,适配器会在宿主应用 overrides 后显式绘制。Pixi 对象的坐标、命中和可编辑属性不等同于 DOM 或 Three.js;只有注册的对象可被选择,控件由该对象的能力声明决定。
88
+
89
+ ## 可直接作为 `.mjs` 文件使用的起点
90
+
91
+ 下面的模块有真实场景、相机、可编辑 Mesh、颜色更新与独立绘制步骤。保存后通过“导入素材”加载;也可把它放进一个 HTML 文件的内联 `<script type="module">` 中。
92
+
93
+ ```js
94
+ export default async function mount({ root, props, viewport, modules }) {
95
+ const { THREE } = modules;
96
+ const renderer = new THREE.WebGLRenderer({ alpha: true, antialias: true });
97
+ renderer.setPixelRatio(1);
98
+ renderer.setSize(viewport.width, viewport.height, false);
99
+ root.appendChild(renderer.domElement);
100
+ const scene = new THREE.Scene();
101
+ scene.name = '图形场景';
102
+ const camera = new THREE.PerspectiveCamera(45, viewport.width / viewport.height, 0.1, 100);
103
+ camera.name = '主相机';
104
+ camera.userData.address = 'main-camera';
105
+ camera.position.set(0, 0, 5);
106
+ const mesh = new THREE.Mesh(
107
+ new THREE.BoxGeometry(),
108
+ new THREE.MeshStandardMaterial({ color: props.color ?? '#3db7ff' }),
109
+ );
110
+ mesh.name = '主立方体';
111
+ mesh.userData.address = 'main-cube';
112
+ const light = new THREE.AmbientLight(0xffffff, 2);
113
+ light.name = '环境光';
114
+ light.userData.address = 'ambient-light';
115
+ scene.add(mesh, light);
116
+
117
+ return {
118
+ scene,
119
+ camera,
120
+ update({ props: next }) { mesh.material.color.set(next.color ?? '#3db7ff'); },
121
+ render({ timeSeconds }) {
122
+ mesh.rotation.set(timeSeconds * 0.3, timeSeconds * 0.5, 0);
123
+ },
124
+ draw() {
125
+ renderer.render(scene, camera);
126
+ },
127
+ dispose() {
128
+ renderer.dispose();
129
+ mesh.geometry.dispose();
130
+ mesh.material.dispose();
131
+ renderer.domElement.remove();
132
+ },
133
+ };
134
+ }
135
+ ```
136
+
137
+ 修改这个起点时,保持生命周期与稳定地址的作用,按实际任务替换内容和视觉设计。更多完整模块见 [示例](examples.md)。
138
+
139
+ ### 4. 加载、调整与更新
140
+
141
+ 1. 将源文件写到明确目录,保留可读源码及素材来源。
142
+ 2. 在 Studio 中通过“添加素材”导入单文件 `.mjs` / `.js`,或打开包含 `index.html` 的本地 HTML 项目目录;源码落盘不代表进入预览。
143
+ 3. 调用方分别保存片段布局、图形 props、对象和相机 overrides。
144
+ 4. HTML 项目目录内的源文件由 Studio 自动监听;普通导入素材需要重新导入/替换。公共包本身不监听磁盘。
145
+ 5. 保持同一对象的稳定地址,检查失效地址,不把旧修改转给无关对象。
146
+
147
+ 在浏览器观察实际画面。可选本地自动化工具只能辅助导入、seek 与截图;它不是在线服务,不应成为图形运行时的依赖。只报告已经完成的导入、调整和导出操作。
148
+
149
+ ### 5. 验证实际画面和编辑行为
150
+
151
+ 按 [验证与故障定位](validation.md) 检查:
152
+
153
+ - 首帧、入场结束、信息最多的停留帧、最大运动幅度、退场和末帧。
154
+ - 同一时刻正向、倒序和重复 seek 的像素状态。
155
+ - 默认参数与明显不同的颜色值,确认控制值真正影响画面。
156
+ - 需要编辑的 Mesh 命中、XYZ 拖动,以及旋转或缩放整个片段后的命中。
157
+ - 对象移动不改变片段 bounds,片段移动不改内部对象的数值。
158
+ - 同地址源码替换保留修改,地址消失时不把修改转给其他对象。
159
+ - 导出的画面包含编辑结果,不包含手柄和控制框。
160
+
161
+ 源文件能解析、界面显示加载完成、某个控件变了,都不能单独证明最终画面正确。没有可用浏览器时,可以验证源码和接口,但在交付中明确指出视觉、命中和导出尚未实测。
162
+
163
+ ## 交付时说明
164
+
165
+ 给出入口文件及依赖素材路径、图形用途、默认画面和时长假设、可编辑对象地址与参数、导入或替换的具体方式,以及实际检查的时间点和结果。仅交付了源码时不要写“已放入时间轴”;没有导出文件时不要写“已生成视频”。
166
+
167
+ 用户拿到文件后,应能知道怎样显示它、怎样调整它、哪些修改会在重载后保留,以及当前 UI 还不能调整哪些值。
@@ -0,0 +1,12 @@
1
+ # Local HEVC Main 10 encoder
2
+
3
+ `createHevcEncoder({ width, height, frameRate, bitrate, signal? })` starts a dedicated Worker. Call `encode(Uint16Array)` sequentially with planar Y, U, V 4:2:0 samples in limited-range 10-bit BT.2020 HLG, stored in 16-bit words. Each result contains Annex B HEVC `data`, a `key` flag and a `codec` string read from the actual SPS. Abort the optional signal to stop initialization or active encoding; call `dispose()` after export. The input buffer remains owned by the caller.
4
+
5
+ Alternatively, `encodeLinearP3(Float32Array)` accepts unpremultiplied linear Display P3 RGBA, with 1 representing 203 cd/m². It composites alpha onto black, converts P3 to BT.2020, applies the inverse HLG reference OOTF (1000 nit peak, system gamma 1.2) and the HLG OETF, then downsamples chroma to limited-range YUV420. This conversion runs inside the Worker. `linearP3ToHlg420()` exposes the same conversion independently for consumers with another encoder. Inputs above reference white retain highlight information up to the target peak; already clipped SDR pixels cannot recover missing highlights.
6
+
7
+ The conversions follow [CSS Color 4](https://www.w3.org/TR/css-color/#color-conversion-code) and [BT.2100 HLG equations](https://registry.khronos.org/DataFormat/specs/1.4/dataformat.1.4.html#TRANSFER_HLG). The output stream declares BT.2020 primaries, HLG transfer and BT.2020 nonconstant-luminance YCbCr.
8
+
9
+ The bundled encoder is Kvazaar 2.3.2, revision `6040962bed5cc68c5ad01234c38c08b8b2822068`, built for 10-bit pixels with Emscripten 7.0.0. It uses a single worker, no pthreads, and a low-delay GOP. Width and height must be positive even integers. Software encoding performance depends on resolution and hardware.
10
+
11
+ The npm CLI includes the compiled encoder. End users do not need Emscripten or CMake.
12
+ If bundled resources are missing, reinstall the matching CLI version and run doctor.