@aixcut/vibevideo 0.0.0-stage → 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.
- package/README.md +80 -2
- package/bin/vibevideo.mjs +12 -0
- package/dist/licenses/KVAZAAR-LICENSE +28 -0
- package/dist/licenses/PIXI-LICENSE +21 -0
- package/dist/licenses/PRORES-WASM-ENCODER-LICENSE +502 -0
- package/dist/licenses/THREE-LICENSE +21 -0
- package/dist/project-template.json +105 -0
- package/dist/skills/vibevideo/SKILL.md +75 -0
- package/dist/skills/vibevideo/assets/pixi/01-kinetic-title.mjs +76 -0
- package/dist/skills/vibevideo/assets/pixi/02-flow-map.mjs +76 -0
- package/dist/skills/vibevideo/assets/pixi/03-nested-board.mjs +69 -0
- package/dist/skills/vibevideo/assets/pixi/04-compact-callout.mjs +40 -0
- package/dist/skills/vibevideo/assets/pixi/README.md +11 -0
- package/dist/skills/vibevideo/references/authoring.md +160 -0
- package/dist/skills/vibevideo/references/editing-and-reload.md +99 -0
- package/dist/skills/vibevideo/references/editor-connection.md +44 -0
- package/dist/skills/vibevideo/references/examples.md +230 -0
- package/dist/skills/vibevideo/references/graphic-workflow.md +167 -0
- package/dist/skills/vibevideo/references/hevc-encoder.md +12 -0
- package/dist/skills/vibevideo/references/runtime-api.md +211 -0
- package/dist/skills/vibevideo/references/validation.md +109 -0
- package/dist/skills/vibevideo-cli/SKILL.md +86 -0
- package/dist/skills/vibevideo-cli/references/agent-protocol.md +39 -0
- package/dist/skills-manifest.json +14 -0
- package/dist/studio/assets/browser-CjQ96pZb.js +671 -0
- package/dist/studio/assets/browserAll-0i6gm1iO.js +14 -0
- package/dist/studio/assets/esbuild-BaXVPFT2.wasm +0 -0
- package/dist/studio/assets/index-DqX5Prpj.js +9687 -0
- package/dist/studio/assets/index-NSprgeey.css +1 -0
- package/dist/studio/assets/prores-encoder-mediabunny-DjdaA3bm.js +2 -0
- package/dist/studio/assets/webworkerAll-Xo9FRLTy.js +102 -0
- package/dist/studio/assets/worker-Bc-itjNu.js +3057 -0
- package/dist/studio/fonts/system/manifest.json +765 -0
- package/dist/studio/index.html +4 -0
- package/dist/studio/sandbox-runtime.js +8593 -0
- package/package.json +10 -4
- package/src/cli.mjs +140 -0
- package/src/project.mjs +19 -0
- package/src/server.mjs +115 -0
- package/src/skills.mjs +110 -0
|
@@ -0,0 +1,211 @@
|
|
|
1
|
+
# HTML、Three.js 与 PixiJS 图形运行时契约
|
|
2
|
+
|
|
3
|
+
本文件说明公共 HTML 宿主协议。实现依据是 `packages/html-host/src/{module-source,sandbox,sandbox-runtime,load,types}.ts`。修改运行时后要同步核对本文件。
|
|
4
|
+
|
|
5
|
+
Studio 使用 nle-video 时间轴,并提供本地 HTML、Three.js 和 PixiJS 预览、命中、场景编辑和本地导出。开源版本不连接后端、AI 对话或同步服务。
|
|
6
|
+
|
|
7
|
+
## 源画面与实际内容范围
|
|
8
|
+
|
|
9
|
+
`viewport` 是透明源画面的坐标空间;它不是图形在最终视频中的显示尺寸。Studio 导入时会按 120 fps 渲染完整时长,并在每帧上以 viewport 的 1/4 宽高分析非透明像素,再把每个分析像素扩成覆盖其源画面像素块的保守边界。120 fps 覆盖当前导出支持的最高帧率。默认摆放会按该范围裁出素材并在项目画布上居中;范围按源码、样式、尺寸、时长、分析帧率和分析分辨率缓存到本地项目,源码变化后会重新分析。全透明动画保留完整 viewport。这个分析会增加首次导入耗时,长动画耗时随帧数增长。
|
|
10
|
+
|
|
11
|
+
通常无需手写范围。若设计需要保留透明留白,或阴影/发光需要超出当前渲染帧 alpha 的装饰空间,可显式声明完整内容范围覆盖自动结果:
|
|
12
|
+
|
|
13
|
+
```html
|
|
14
|
+
<meta name="vibevideo:viewport" content="1280x720">
|
|
15
|
+
<meta name="vibevideo:content-bounds" content="320,220,640,280">
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
单文件 `.mjs` 使用源码头部注释:
|
|
19
|
+
|
|
20
|
+
```js
|
|
21
|
+
// @vibevideo:content-bounds 320,220,640,280
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
内容范围格式为 `x,y,width,height`,单位是源画面的像素,必须位于 `viewport` 内。范围应包含完整动画的移动、旋转、描边和发光边缘。Studio 保留完整透明源画面并在合成时用此范围裁切,编辑器拖动和缩放针对裁后的有效内容。透明度为 0 的像素不会纳入自动范围;背景或动效覆盖全画面时会自动得到完整 viewport。
|
|
25
|
+
|
|
26
|
+
## 文件与入口
|
|
27
|
+
|
|
28
|
+
可导入单个 `.mjs` / `.js`,或选择一个 HTML 项目文件夹。项目入口优先取 `index.html`;否则文件夹中必须只有一个 HTML 文件。Studio 会打包入口引用的相对 JavaScript/TypeScript/JSX、CSS、JSON、图片和字体文件,图片与字体会内嵌到沙箱模块中。相对依赖必须位于所选目录内;`node_modules`、构建目录和隐藏的 `.git` 目录不会导入。
|
|
29
|
+
|
|
30
|
+
HTML 项目可以用 `data-vibevideo-address` 标记需要稳定选择和编辑的元素:
|
|
31
|
+
|
|
32
|
+
```html
|
|
33
|
+
<div data-vibevideo-address="headline">可在 Studio 选中的标题</div>
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
HTML 项目应提供一个 module 入口:
|
|
37
|
+
|
|
38
|
+
```html
|
|
39
|
+
<!doctype html>
|
|
40
|
+
<html>
|
|
41
|
+
<script type="module">
|
|
42
|
+
export default function mount({ root, viewport }) {
|
|
43
|
+
const canvas = document.createElement('canvas');
|
|
44
|
+
canvas.width = viewport.width;
|
|
45
|
+
canvas.height = viewport.height;
|
|
46
|
+
root.appendChild(canvas);
|
|
47
|
+
const context = canvas.getContext('2d');
|
|
48
|
+
return {
|
|
49
|
+
render() {},
|
|
50
|
+
draw() {
|
|
51
|
+
context.clearRect(0, 0, canvas.width, canvas.height);
|
|
52
|
+
context.fillStyle = '#3db7ff';
|
|
53
|
+
context.fillRect(40, 40, canvas.width - 80, canvas.height - 80);
|
|
54
|
+
},
|
|
55
|
+
dispose() { canvas.remove(); },
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
</script>
|
|
59
|
+
</html>
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
项目导入器支持一个内联 module,或一个带 `src` 的 module。HTML 正文会挂载到隔离容器,内联和相对链接的 CSS 会一起编译;单纯 HTML/CSS 动画可随时间轴采样。也可以不含脚本,作为静态 HTML/CSS 内容导入。页面图片、poster、SVG href 等本地引用会内嵌。多个 module 入口和普通 script 不支持。
|
|
63
|
+
|
|
64
|
+
推荐明确写 `export default function mount(...)` 或 `export default async function mount(...)`。先定义函数再 `export default mount;`、默认导出箭头函数、`export function mount(...)`、`export { mount as default }` 也可用。当前编译器不提供完整的 ESM 模块图;其他顶层 export 和动态 import 仍不支持。TS、TSX、JSX 必须先在外部转为符合此入口形式的 JavaScript。
|
|
65
|
+
|
|
66
|
+
本地项目目录模式会在源码根目录写入 `vibevideo.project.json`,其中时间轴直接引用 HTML 入口和已使用的依赖文件;源文件本身不会被编辑器覆写。刷新或重新打开同一目录可恢复时间轴,已记录依赖文件的外部修改会自动重新编译并刷新预览。单独导入的 HTML 也会打包目录文件,但只有选中本地项目目录时才会监听源文件改动。导出使用同一组依赖文件重新编译。
|
|
67
|
+
|
|
68
|
+
## 模块来源
|
|
69
|
+
|
|
70
|
+
优先从 mount 上下文取库:
|
|
71
|
+
|
|
72
|
+
```js
|
|
73
|
+
const { THREE, gsap } = modules;
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
以下静态导入形式也由宿主处理:
|
|
77
|
+
|
|
78
|
+
```js
|
|
79
|
+
import * as THREE from 'three';
|
|
80
|
+
import { Vector3, Mesh as Mesh3D } from 'three';
|
|
81
|
+
import { gsap } from 'gsap';
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
命名导入的符号必须确实属于该模块。使用 `gsap` 命名导出或 `modules.gsap` 作为动画对象,不把模块 namespace 当作动画实例。
|
|
85
|
+
|
|
86
|
+
宿主注册 `three`、`gsap` 和 `pixi.js`(PixiJS 8.23.0)。项目目录中的相对模块与 CSS 可由项目编译器打包;未提供的外部 npm 依赖、CDN、Three.js addons、`three/webgpu`、React Three Fiber、D3、Lottie、Remotion 和 GSAP 插件不属于这个契约。
|
|
87
|
+
|
|
88
|
+
## mount 上下文
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
interface MountContext {
|
|
92
|
+
root: HTMLElement;
|
|
93
|
+
props: Record<string, unknown>;
|
|
94
|
+
timeline: { timeSeconds: number };
|
|
95
|
+
viewport: { width: number; height: number };
|
|
96
|
+
modules: { THREE: typeof THREE; PIXI: typeof import('pixi.js'); VIBEVIDEO: typeof import('@vibevideo/html-host'); gsap: typeof gsap; gsapModule: unknown };
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
| 字段 | 作者应该怎样使用 |
|
|
101
|
+
| --- | --- |
|
|
102
|
+
| `root` | 本次实例拥有的挂载容器。HTML 项目的 body 内容和样式会先放入容器;模块可查询它们并创建 canvas,只清理自己创建的节点。 |
|
|
103
|
+
| `props` | 初始参数快照。新导入图形通常是 `{}`,源码提供合理默认值。 |
|
|
104
|
+
| `timeline.timeSeconds` | 加载时传入的时间,不是持续更新的时钟。逐帧动画以 render 的参数为准。 |
|
|
105
|
+
| `viewport` | 源画面像素尺寸,不等于片段在最终画布中的尺寸。用它设置 renderer/canvas。 |
|
|
106
|
+
| `modules` | 宿主提供的 Three.js、GSAP、PixiJS 和场景适配 API;不需要在页面中安装包或加载 CDN。 |
|
|
107
|
+
|
|
108
|
+
每个时间轴片段有自己的沙箱实例。不要通过全局变量把对象、props 或播放状态共享给其他片段。
|
|
109
|
+
|
|
110
|
+
## 生命周期与顺序
|
|
111
|
+
|
|
112
|
+
`mount` 可以返回 Promise。返回对象包含:
|
|
113
|
+
|
|
114
|
+
```ts
|
|
115
|
+
interface MountedGraphic {
|
|
116
|
+
render(time: { frame: number; progress: number; timeSeconds: number }): void;
|
|
117
|
+
/** Optional export-resolution hook. Keep authored coordinates in `sourceViewport`; increase the backing store to `outputViewport`. */
|
|
118
|
+
resize?(outputViewport: { width: number; height: number }, sourceViewport: { width: number; height: number }): void;
|
|
119
|
+
draw?(): void;
|
|
120
|
+
update?(input: { props: Record<string, unknown> }): void;
|
|
121
|
+
dispose(): void;
|
|
122
|
+
scene?: THREE.Scene;
|
|
123
|
+
camera?: THREE.Camera;
|
|
124
|
+
sceneAdapter?: SceneAdapter;
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
宿主渲染句柄的 `render(time, { outputViewport })` 可请求最高 8192 × 8192 的输出像素尺寸。HTML/CSS 快照和 Studio 合成会按此尺寸绘制。自管 Canvas、WebGL 或 Three.js renderer 的图形应实现可选 `resize(outputViewport, sourceViewport)`,在保持源视口坐标与动画布局不变的前提下提高绘图缓冲区分辨率;宿主每帧都传入目标尺寸,因此返回源尺寸预览时也必须恢复缓冲区。没有实现该钩子的 canvas/WebGL 内容会按其现有像素缓冲区缩放,不能保证 4K 原生细节。Pixi 场景适配器会自动按导出比例提高 renderer 分辨率。视频和静态图片素材仍受源素材分辨率限制。
|
|
129
|
+
|
|
130
|
+
宿主另提供 `renderFloat(time, { outputViewport, overrides })`:返回 `{ width, height, pixels }`,其中 `pixels` 为 Display P3、非预乘 Alpha 的 RGBA 半精度浮点数据,按行排列,每个通道占两个字节。该接口通过原始缓冲区跨沙箱传输,以保留大于 1 的亮度值;它要求浏览器支持 `display-p3` 浮点 Canvas。普通 `render()` 返回的 ImageBitmap 不保证保留这些值。源画布、素材和着色器如果已经把亮度截断,浮点捕获不能恢复丢失的细节;此接口本身也不编码 HDR 视频。
|
|
131
|
+
|
|
132
|
+
`SceneAdapter` 是公开的渲染器中立接口,承载节点列表、命中、四角几何、轴对齐 bounds、属性覆盖、显式绘制和释放。其数据使用稳定地址、二维/三维变换与 `editableCapabilities`,不要求调用方依赖 Pixi 或 Three 类型。Pixi 返回经场景变换的局部 bounds 四角;Three 对象返回投影包围盒的四角。HTML 优先使用浏览器提供的 `getBoxQuads()` 返回变换后四角,不支持时退回轴对齐矩形。HTML 命中还返回 `styleProperties.supported` 与对应计算样式;编辑器按该列表显示控件。PixiJS 首个适配器通过 `modules.VIBEVIDEO.createPixiSceneAdapter()` 实现该接口;作者不需要在 Studio 或时间轴中加入引擎专用逻辑。
|
|
133
|
+
|
|
134
|
+
命中结果携带当前源码版本指纹。编辑器持久化对象覆盖时同时保存该指纹;源码、样式、标记或 viewport 改变后,旧版本的选择结果和覆盖不再作用到新场景。
|
|
135
|
+
|
|
136
|
+
新图形返回独立的 `draw()`。一次帧请求实际执行:
|
|
137
|
+
|
|
138
|
+
1. 宿主恢复 mount 或最近一次 update 记录的对象、相机变换基线。
|
|
139
|
+
2. 调用作者的 `render(time)` 求值该时刻。
|
|
140
|
+
3. 宿主应用当前片段的 Three.js 对象、已注册 Pixi 节点和 HTML 元素 overrides。
|
|
141
|
+
4. Pixi 场景由适配器显式绘制;其他图形调用作者的 `draw()`(或兼容旧图形在 `render()` 内绘制)。
|
|
142
|
+
5. 捕获输出:单一 canvas 直接捕获;混合 DOM 会按元素布局栅格化背景、边框、文字,以及图片、视频和 canvas 内容,再生成 ImageBitmap;支持简单 `::before` / `::after` 内容、`clip-path: inset/circle/ellipse/polygon`,常见文字样式包含字体、字重、斜体、下划线、单层文字阴影和描边;CSS Web Animations 会 seek 到请求时刻。
|
|
143
|
+
|
|
144
|
+
只返回 render、在 render 内直接绘制的旧图形仍能加载,但宿主随后应用的场景修改来不及进入已经画好的帧。需要内部编辑时,把求值与绘制拆开。Pixi 应用不要启用自动 ticker 渲染;每次 render 都依据 `timeSeconds` 设置节点状态,适配器在宿主完成属性覆盖后显式调用 renderer。
|
|
145
|
+
|
|
146
|
+
### mount:准备完整实例
|
|
147
|
+
|
|
148
|
+
创建一次 renderer、场景、相机、几何和材质。Pixi 应用同样在 mount 中初始化并关闭 `autoStart`。纹理、图片与字体解码必须在返回前完成,失败时拒绝 mount 并释放已创建的资源。渲染阶段不要边显示占位图边等待后台资源到达。
|
|
149
|
+
|
|
150
|
+
把渲染尺寸绑定到 `viewport`,通常使用 `renderer.setPixelRatio(1)` 和 `renderer.setSize(width, height, false)`。不要从窗口大小或 devicePixelRatio 推断输出尺寸。不同显示器上的源像素应一致。
|
|
151
|
+
|
|
152
|
+
若用 canvas 制作文字纹理,不要把辅助 canvas 挂到 root 的最终画布之前;宿主只捕获找到的第一个 canvas。
|
|
153
|
+
|
|
154
|
+
### render:同步重建当前时刻
|
|
155
|
+
|
|
156
|
+
- `timeSeconds` 是片段内经过的秒数。
|
|
157
|
+
- `frame` 是 `Math.round(timeSeconds * fps)`。
|
|
158
|
+
- `progress` 是当前秒数除以片段时长,并截到 0–1。
|
|
159
|
+
- 同一秒数在不同帧率下应得到同一场景状态。用秒数表达时长,只有确实按片段比例变化的动画使用 progress。
|
|
160
|
+
- 可按 `0 → 2 → 1 → 1 → 0` 任意顺序调用。不要依赖上一帧、调用次数或墙钟。
|
|
161
|
+
|
|
162
|
+
正确的逐帧表达是 `mesh.rotation.y = timeSeconds * speed`,不是 `mesh.rotation.y += speed / 30`。随机布局应在 mount 中由固定种子和对象索引建立;粒子、物理或路径运动用解析函数、可重建状态或预计算采样实现。
|
|
163
|
+
|
|
164
|
+
`render` 不返回 Promise。`async render()` 会被拒绝。不要使用 `Date.now()`、`performance.now()`、独立的 `requestAnimationFrame`、`setAnimationLoop`、自动播放的 GSAP/CSS/Web Animations 或 timer 推进画面。源校验只检查部分禁用形式,未报错不等于符合确定性约定。
|
|
165
|
+
|
|
166
|
+
GSAP 应建立暂停的 timeline,按传入秒数 seek;把求值结果存到普通状态对象,再在每次 render 中显式写到 Three.js 对象。完整模式见 [示例](examples.md#gsap-外部时钟与可编辑场景)。
|
|
167
|
+
|
|
168
|
+
### draw:绘制应用修改后的场景
|
|
169
|
+
|
|
170
|
+
Three.js 中通常只调用 `renderer.render(scene, camera)`。PixiJS 由场景适配器显式调用 `app.renderer.render({ container: app.stage })`。不要在最终绘制阶段重设编辑目标的 position、camera.lookAt、rotation 或 scale,否则会覆盖刚刚应用的用户修改。
|
|
171
|
+
|
|
172
|
+
Canvas 2D 每帧先清空画布,再根据 render 计算的状态绘制。使用 `save()` / `restore()` 隔离 alpha、transform、clip、shadow 等状态,避免重复或倒序请求产生累积。
|
|
173
|
+
|
|
174
|
+
### update:参数真正进入画面
|
|
175
|
+
|
|
176
|
+
`update({ props })` 当前按同步方法使用;不要启动异步字体或图片加载。需要新的异步资源时,通过源码替换重新完成 mount,或由调用方设计并验证明确的异步更新协议。
|
|
177
|
+
|
|
178
|
+
在 update 中合并源码默认值和传入值,再更新实际资源。使用 `??` 保留合法的 `0`、`false`、空字符串。字体或文字改变时重绘文字 canvas,并设置 `texture.needsUpdate = true`;改颜色时调用实际材质的颜色 setter。
|
|
179
|
+
|
|
180
|
+
当前 UI 只绑定 `props.color`。在源码里写一个参数定义数组不会出现 title、font、speed 或 image 选择器。其他参数可以供公开 handle 的 update 调用方使用,但交付时区分“代码接受该参数”和“当前 UI 有该控件”。
|
|
181
|
+
|
|
182
|
+
通用颜色控件的默认显示值是 `#3db7ff`,导入器不会从源码推断品牌默认色。需要初始控件与画面一致时使用一致的默认值,或在导入后明确设置颜色。
|
|
183
|
+
|
|
184
|
+
### dispose:释放实例所有权
|
|
185
|
+
|
|
186
|
+
释放本实例创建的 geometry、material、texture、renderer 和 GSAP timeline,移除本实例挂到 root 的节点,清理事件和自行创建的 object URL。Pixi 适配器默认只停止它所连接的 ticker;仅当该应用由当前图形独占时,才用 `ownsApplication: true` 交给适配器销毁 renderer 与显示树。共享的 Pixi `Assets`、texture source 只由资源所有者释放。
|
|
187
|
+
|
|
188
|
+
宿主负责片段导入的媒体 URL、消息通道和沙箱 iframe;作者仍负责自己创建的图形资源。初始化中途失败时,不要等一个永远不会成功返回的 handle 来清理资源。
|
|
189
|
+
|
|
190
|
+
## 素材、字体与捕获边界
|
|
191
|
+
|
|
192
|
+
沙箱是 opaque-origin iframe,当前 CSP 允许 data/blob 图片和字体,阻止 fetch、外部脚本、子 iframe、音视频加载和远端 stylesheet。
|
|
193
|
+
|
|
194
|
+
- 固定 logo、图片、纹理:在导入前把真实文件编码成 data URL,直接包含在自包含模块中,在 mount 中解码。旁边的 `./logo.png`、`file://` 和项目 asset ID 不会自动解析。
|
|
195
|
+
- 普通视频和图片:通过编辑器作为独立片段导入。图形本身保持透明,避免另建一个不能与宿主同步的 video 播放器。
|
|
196
|
+
- 自定义字体:可把允许使用的字体编码为 data URL,通过 `FontFace` 加载并加入本 iframe 的 `document.fonts`,await 完成后测量和绘制。没有远端字体目录或自动字体下载。
|
|
197
|
+
- 标题或标签:Canvas 2D 可直接绘制;3D 文字可由 CanvasTexture + Mesh 表示。混合 DOM 捕获覆盖常见文字样式、纯色背景、多层线性/径向/圆锥渐变、圆角、多重外盒阴影、单层文字阴影、渐变 Alpha/亮度遮罩、二维变换、inset/circle/ellipse/polygon 裁剪、简单伪元素、Canvas filter 与常用 blend mode、SVG、图片、视频和 canvas 节点。透明度按元素及其后代的整体合成。该捕获器不是浏览器整页截图:复杂生成内容、图片背景/图片遮罩、内阴影、完整 CSS 堆叠上下文与 3D CSS transform 尚未达到浏览器原生绘制的像素保真;这类关键视觉应使用 SVG、Canvas、Three.js 或 PixiJS 绘制,并在目标视口检查输出。
|
|
198
|
+
|
|
199
|
+
纹理的完整步骤见 [示例](examples.md#固定图片与文字纹理)。用 `TextureLoader` 解码彩色图片后设置适当的色彩空间,例如 `THREE.SRGBColorSpace`;数据纹理按其数据含义处理。不要为了迁就加载边界重新绘制必须保真的用户商标或产品图。
|
|
200
|
+
|
|
201
|
+
## 透明与导出
|
|
202
|
+
|
|
203
|
+
透明 Three.js 图形使用 `WebGLRenderer({ alpha: true })`,避免设置不需要的 `scene.background`。Canvas 2D 使用透明 clearRect,不添加额外实色底。源透明区域可与时间轴下层合成,但本地 WebM 合成结果的 alpha 是否保留不属于当前承诺。
|
|
204
|
+
|
|
205
|
+
Studio 提供 MP4、MOV、WebM、带 Alpha 的 ProRes 4444 MOV,以及 Rec.2100 HLG MP4。可指定输出宽高、帧率、码率和范围;4K 输出已验证。音频片段和视频原声在本地解码、混音,遵循轨道静音、片段音量、淡入淡出及播放速率。AAC 使用当前浏览器实测编码延迟设置呈现范围;WebM 使用 Opus,ProRes 使用 PCM。项目数据保存在用户选择的本地目录;开源版本没有后端同步或 AI 对话接口。
|
|
206
|
+
|
|
207
|
+
HLG 导出通过 `renderFloat()` 保留超出 SDR 白色的图形像素,以线性 Display P3 合成,再转换为 BT.2020、HLG 和 10 位 YUV420,由本地 WASM Worker 编码 HEVC Main 10。参考白为 203 cd/m²,目标峰值为 1000 cd/m²;不是只给 SDR 文件添加 HDR 标记。SDR 图片、视频和普通 WebGL 画布不会因此获得额外的高光细节。HDR Canvas 源须使用 `getContext('2d', {colorSpace:'display-p3', colorType:'float16'})`,并用 `color(display-p3 1.4 1.4 1.4)` 等超白值绘制高光;保持透明处 Alpha 为 0。浏览器不支持浮点画布时会明确报错。编码器公共接口、输入格式及重建步骤见 [HEVC 包说明](hevc-encoder.md)。
|
|
208
|
+
|
|
209
|
+
导出是按请求时刻的离线渲染,编码速度受场景、分辨率和机器性能影响;不承诺任意复杂内容都能实时播放。自管 Canvas/Three renderer 应实现上面的 `resize()`,避免把低分辨率像素单纯拉伸到 4K。
|
|
210
|
+
|
|
211
|
+
只导入可信图形源码。iframe 隔离和 CSP 仍不是完整的不可信代码安全边界:页面可自行导航,props 会传给图形。不要把密钥等秘密放入 props。
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# 验证与故障定位
|
|
2
|
+
|
|
3
|
+
## 可验证的结果
|
|
4
|
+
|
|
5
|
+
把以下状态分开记录:源文件已写入、导入成功、预览实际出现、参数实际生效、内部对象可编辑、导出文件已检查。完成前一个状态不代表后一个状态也已完成。
|
|
6
|
+
|
|
7
|
+
仅交付源码的任务不要求替用户执行时间轴操作。若工具不能操作浏览器,说明已完成的源码检查以及尚未实测的画面、命中和导出;不要把手动操作步骤写成已经执行的结果。
|
|
8
|
+
|
|
9
|
+
## 当前可用命令
|
|
10
|
+
|
|
11
|
+
Studio 位于 `apps/studio`,使用 nle-video 时间轴并提供本地 HTML 项目目录导入。项目目录模式需要支持 File System Access API 的 Chromium 浏览器。
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
npm run build:html-host
|
|
15
|
+
npm run typecheck
|
|
16
|
+
npm test
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Studio 构建还会打包 esbuild WASM,用于浏览器端编译多文件 HTML 项目。构建成功不证明实际画面、命中、外部修改自动刷新或导出已通过验收。
|
|
20
|
+
|
|
21
|
+
以下操作是实际编辑器能力的验收清单;尚未执行的项目应标成待验证,不应因为源码已接通就写为通过。
|
|
22
|
+
|
|
23
|
+
## 单个交付物的操作顺序
|
|
24
|
+
|
|
25
|
+
### 1. 导入与首帧
|
|
26
|
+
|
|
27
|
+
通过素材库导入单个 HTML,或在“打开 → HTML 项目目录”选择含 `index.html` 的项目文件夹。确认片段出现在时间轴,预览中有实际图形,并检查错误区域。不要把列表中的文件名当作渲染成功。
|
|
28
|
+
|
|
29
|
+
对透明图形,观察有内容的像素和透明区域;放到实际下层素材上检查遮挡。不要只在纯黑背景上判断 alpha。核对 canvas 源尺寸与绘制内容,特别是源边缘是否裁掉入场或放大运动。
|
|
30
|
+
|
|
31
|
+
### 2. 时序、倒序与重复请求
|
|
32
|
+
|
|
33
|
+
按素材声明的时长与项目帧率检查这些本地时刻,不套用旧界面默认值:
|
|
34
|
+
|
|
35
|
+
| 时刻 | 检查内容 |
|
|
36
|
+
| --- | --- |
|
|
37
|
+
| 0 | 首帧不依赖之前播放;有意从透明开始时仍应验证后续状态 |
|
|
38
|
+
| 入场结束 | 主体或文字位置、大小、透明度到达设计值 |
|
|
39
|
+
| 2 秒 | 中段的实际可读内容与运动状态 |
|
|
40
|
+
| 最大运动幅度 | 位移、放大、旋转、描边、阴影不意外裁切 |
|
|
41
|
+
| 时长 − 1/fps | 最后一个可见帧;不能依赖精确时长这一非活动边界显示内容 |
|
|
42
|
+
|
|
43
|
+
按 `0 → 2 → 末帧 → 2 → 0 → 2` 跳转。同一时刻应得到同一状态。对于有模拟或随机外观的图形,除“看起来类似”以外,也检查对象布局、数值和种子是否一致。
|
|
44
|
+
|
|
45
|
+
不同帧率的宿主调用方应以同一秒数比较状态,不以相同 frame 数比较。PixiJS 特别检查应用未启动自动 ticker,重复与倒序请求不会累加变换。当前参考 UI 固定 30 fps,没有帧率切换控件。
|
|
46
|
+
|
|
47
|
+
运行 Pixi 案例时,可按案例时长采样,例如仓库示例采用 5 秒片段,检查 `0 → 3 → 1.5 → 1.5`。比较同一时刻的实际画面像素,确认倒序返回和重复求值相同;不得用页面动画播放顺畅代替确定性检查。
|
|
48
|
+
|
|
49
|
+
### 3. 参数可见性
|
|
50
|
+
|
|
51
|
+
先检查源码默认画面,再把颜色设成明显不同的值。检查实际材质、文字或纹理像素改变,倒序 seek 后仍保留参数效果。
|
|
52
|
+
|
|
53
|
+
其他参数需要相应的调用入口;没有 UI 控件时,不把它描述成“可在属性面板修改”。源码默认值与传入的 props 冲突时,以当前 props 为准定位。
|
|
54
|
+
|
|
55
|
+
### 4. 场景编辑
|
|
56
|
+
|
|
57
|
+
需要内部编辑的交付物检查:
|
|
58
|
+
|
|
59
|
+
1. 选中图形片段并点中已注册的 HTML、Three.js 或 PixiJS 对象;Three.js 无三角形对象可从对象列表中选择。
|
|
60
|
+
2. 对比选中对象的名称、地址和画面中的形体,不能只是任意近邻。
|
|
61
|
+
3. 对 Pixi 对象拖动选框并调整其已声明的变换控件;对 Three.js 对象拖动投影手柄,观察位置数值与实际像素都变化。
|
|
62
|
+
4. 编辑内部对象后,整段片段的 bounds 不应变化。
|
|
63
|
+
5. 旋转或缩放整个片段,再点中同一内部对象。
|
|
64
|
+
6. seek 到另一个时刻再返回,编辑结果仍属于同一对象;对于 Pixi,还应选择不同的注册对象并确认属性控件随对象能力变化。
|
|
65
|
+
7. 测试需要交付的相机和灯光选择;没有三角形的对象从场景列表或相机入口选择。
|
|
66
|
+
8. Escape 或完成编辑后恢复普通片段操作;取消拖动不留下半途值。
|
|
67
|
+
|
|
68
|
+
纯 Canvas 2D 图形跳过内部 Mesh 检查,并明确它支持整段片段编辑,不声称每条绘制命令都有 hit test。
|
|
69
|
+
|
|
70
|
+
点击前读取当前预览的位置。属性面板展开、滚动、移动端布局或窗口变化都可能移动预览;自动化应在点击时换算屏幕坐标,不能复用面板变化前的 clientX/clientY。
|
|
71
|
+
|
|
72
|
+
### 5. 修订与隔离
|
|
73
|
+
|
|
74
|
+
已有用户修改时,用“替换图形”检查:同地址对象保留修改;不存在的地址显示失效;失败的新代码保留旧画面。需要多个实例的作品,再检查第二个实例的编辑没有影响第一个实例。
|
|
75
|
+
|
|
76
|
+
源码修改、参数修改和对象 override 分别验证。不要通过悄悄换地址、清空所有 props 或新建另一个片段,让已经保存的修改“看起来不再有问题”。
|
|
77
|
+
|
|
78
|
+
### 6. 导出
|
|
79
|
+
|
|
80
|
+
确认加载完成后使用“导出视频”。格式和编码取当前导出设置实际提供的选项;不要假设一定是 MP4、MOV 或 WebM。等待实际下载完成,读取文件的编码、尺寸和时长,再检查与预览相同的时间点。视频素材要看不同源时刻,不能只用静态缩略图或一段恒定颜色证明时间同步。
|
|
81
|
+
|
|
82
|
+
对象和相机修改应进入最终画面;选区边框、手柄和属性面板不应进入导出。允许编码引起小幅颜色差异,但不能用容差掩盖错帧、错层、错对象或丢失内容。
|
|
83
|
+
|
|
84
|
+
当前导出只有画面。不要把没有声音的结果称为已经完成音频混合,也不要把 WebM 描述成 MP4。
|
|
85
|
+
|
|
86
|
+
## 按故障阶段排查
|
|
87
|
+
|
|
88
|
+
| 现象或错误 | 先检查 | 修复方向 |
|
|
89
|
+
| --- | --- | --- |
|
|
90
|
+
| “只能包含一个内联 module 脚本” | HTML module 的数量、type 和 src | 合并成一个内联入口;正文中的脚本不会自动安装 |
|
|
91
|
+
| “必须导出 mount”或解析错误 | mount 导出语法、JSX/TS、残留 import/export | 交付自包含普通 JavaScript,使用支持的 mount 导出形式 |
|
|
92
|
+
| 模块导入失败 | 是否用了 CDN、远端依赖或未注册库 | 使用 `three`、`gsap`、`pixi.js` 或项目内相对模块;其他外部依赖需先在本地项目中打包 |
|
|
93
|
+
| 纹理或字体无法加载 | 是否仍然引用磁盘路径、远端 URL、asset ID | 在导入前嵌入真实 data URL,并在 mount 中 await 解码 |
|
|
94
|
+
| “没有提供可捕获的 canvas” | 是否只修改 DOM,canvas 是否挂在 root 下 | 创建最终 canvas;Three.js 挂入 renderer.domElement |
|
|
95
|
+
| “render 必须同步完成” | async render、Promise 或 render 内加载 | 把资源准备移到 mount,render 只同步求值 |
|
|
96
|
+
| 正序正常,倒序不一致 | 累加变换、ticker、随机数、依赖旧帧的模拟 | 从秒数重建状态,固定随机参数,暂停并 seek 动画 |
|
|
97
|
+
| 同一时间第二次请求姿态错误 | 动画库跳过重复写入,宿主恢复了基线 | 求值普通 motion 对象,再每次显式写回 Three.js 变换 |
|
|
98
|
+
| 有画面但无法内部选中 | Three 的 scene/camera 是否返回,Pixi 对象是否注册且声明能力 | 返回实际绘制场景或注册 Pixi 显示对象,检查祖先可见性、命中面积与稳定地址 |
|
|
99
|
+
| 选中与数值变化,但画面没变 | 是否在 render 中提前绘制,draw 是否重置变换 | render 求值,宿主应用 overrides 后再 draw |
|
|
100
|
+
| 更改默认颜色后没有变化 | 原片段是否有 props.color | 用实际 props 定位,不删除用户覆盖值来隐藏问题 |
|
|
101
|
+
| 新源码位置与预期不同 | 是否有同地址对象位置 override | 区分新默认值与保留的用户编辑 |
|
|
102
|
+
| “找不到场景地址” | 节点被删、地址改变或重复 | 保留同语义对象的唯一地址;失效修改不得转给无关节点 |
|
|
103
|
+
| 挂载失败或隔离环境超时 | 原错误、资源解码、运行时加载、初始化计算量 | 保留旧片段与源文件;修复原因后显式重试加载或替换 |
|
|
104
|
+
| 导出提示无法维持 30 fps | 场景复杂度、纹理尺寸、逐帧分配和重复加载 | 减少无效开销,再验证;不把失败结果当成功视频 |
|
|
105
|
+
| 刷新页面后素材和修改消失 | 是否误认为存在项目持久化 | 说明会话限制,保留可重建的源码与素材 |
|
|
106
|
+
|
|
107
|
+
## 交付证据
|
|
108
|
+
|
|
109
|
+
简要报告源文件、加载方式、实际采样时刻、参数修改、命中和拖动、是否做过替换及导出。没有执行的步骤明确留作待验证,不填“通过”。视觉设计有参考时,区分忠实复现、已说明的改动和仍缺少的素材。
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vibevideo-cli
|
|
3
|
+
description: Operate the Vibevideo CLI to start local Studio projects, connect an agent session, import and edit graphics, inspect state, and diagnose installation or connection failures.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Vibevideo CLI
|
|
7
|
+
|
|
8
|
+
Use `npx @aixcut/vibevideo@beta`, or `vibevideo` when globally installed. A pinned
|
|
9
|
+
project version takes precedence over a floating tag. Node.js 22+ is required;
|
|
10
|
+
Chrome or Edge is recommended. Use `--help` for the installed version's options.
|
|
11
|
+
|
|
12
|
+
## Projects and server lifetime
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
npx @aixcut/vibevideo@beta init ./my-video --no-open --json
|
|
16
|
+
npx @aixcut/vibevideo@beta open ./my-video --no-open --json
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
`init` refuses an existing directory; `open` requires `vibevideo.project.json`.
|
|
20
|
+
Both commands keep a foreground server running. In an agent harness, keep the
|
|
21
|
+
terminal/process session alive; a returned startup JSON object does not mean the
|
|
22
|
+
command exits. Use the host's persistent process capability. Do not launch a
|
|
23
|
+
second server just because the first command remains running.
|
|
24
|
+
|
|
25
|
+
Startup prints `{ ok, url, project, session }`. Open `url` in the browser,
|
|
26
|
+
including `?agent=1`, and retain the returned `session` file path. Do not print
|
|
27
|
+
the session file's contents: it contains a connection credential. Optional
|
|
28
|
+
`--port 4567` gives a stable origin; an explicit occupied port fails. Default
|
|
29
|
+
ports are selected automatically. Ctrl+C/SIGTERM stops the server and removes
|
|
30
|
+
its session file; no managed background/status/stop CLI subcommands exist yet.
|
|
31
|
+
|
|
32
|
+
## Agent operations
|
|
33
|
+
|
|
34
|
+
Replace `$SESSION` with the startup result's session path:
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
npx @aixcut/vibevideo@beta agent status --session "$SESSION"
|
|
38
|
+
npx @aixcut/vibevideo@beta agent import --file ./title.mjs --session "$SESSION"
|
|
39
|
+
npx @aixcut/vibevideo@beta agent seek --seconds 2 --session "$SESSION"
|
|
40
|
+
npx @aixcut/vibevideo@beta agent inspect --session "$SESSION"
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
`status.connected` becomes true after the open Studio tab finishes loading its
|
|
44
|
+
project and begins polling. `inspect` returns the timeline; it is not a visual
|
|
45
|
+
check. Import supports graphic HTML/JS source, not arbitrary media files; import
|
|
46
|
+
audio/video/images through Studio. For source replacement, duration, object and
|
|
47
|
+
scene commands, read [agent-protocol.md](references/agent-protocol.md).
|
|
48
|
+
|
|
49
|
+
The command waits for a job result. On timeout, inspect Studio/state before
|
|
50
|
+
retrying mutations; the original job may have completed. Graphic authoring and
|
|
51
|
+
runtime contracts are in the adjacent [vibevideo skill](../vibevideo/SKILL.md).
|
|
52
|
+
|
|
53
|
+
## Diagnostics and output
|
|
54
|
+
|
|
55
|
+
`doctor --json` checks Node and bundled assets. Browser codec availability is
|
|
56
|
+
checked by Studio during export, not by this command. Agent results are JSON;
|
|
57
|
+
`--json` also enables machine-readable startup, Skills and diagnostic results.
|
|
58
|
+
Failures exit nonzero; with `--json`, the CLI prints `{ ok:false, error }`.
|
|
59
|
+
|
|
60
|
+
- **Disconnected / 409:** confirm the server is alive, open its exact URL, wait
|
|
61
|
+
for project loading, and check `agent status` using that server's session.
|
|
62
|
+
- **Missing/stale session:** restart/open the project and use the newly printed
|
|
63
|
+
path; do not invent a URL, reuse another project's credential or expose it.
|
|
64
|
+
- **Import fails:** check the graphic's runtime contract and the Studio error.
|
|
65
|
+
Missing npm libraries, remote modules and malformed lifecycle exports are not
|
|
66
|
+
repaired by retrying the same source.
|
|
67
|
+
- **Port occupied:** use automatic selection or another explicit port.
|
|
68
|
+
- **Missing bundled files:** reinstall the matching npm version, then run doctor.
|
|
69
|
+
|
|
70
|
+
## Skill maintenance
|
|
71
|
+
|
|
72
|
+
`skills install` adds missing core Skills. `skills check` compares installed
|
|
73
|
+
content with this CLI's bundled version. `skills update` updates unchanged
|
|
74
|
+
managed copies while preserving local edits and unmanaged folders. There is no
|
|
75
|
+
network fetch during these operations. Use `--agent codex|claude|cursor|universal`
|
|
76
|
+
or `--dir <skills-directory>` to select a destination. Default targets are the
|
|
77
|
+
shared `~/.agents/skills` directory and existing agent configurations. Restart
|
|
78
|
+
or refresh the agent's skill discovery after installation.
|
|
79
|
+
|
|
80
|
+
`init` installs missing core Skills unless `--skip-skills` is passed. It never
|
|
81
|
+
refreshes existing Skills. A Skills failure does not prevent creating a project.
|
|
82
|
+
Do not install or update Skills during an unrelated video edit unless needed or
|
|
83
|
+
requested.
|
|
84
|
+
|
|
85
|
+
Export is currently through Studio's UI. There are no CLI `render`, `snapshot`,
|
|
86
|
+
`lint`, `check`, `timeline`, `skills --force` or media-generation commands.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Studio agent commands
|
|
2
|
+
|
|
3
|
+
For structured operations, write JSON to a local file and run:
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
npx @aixcut/vibevideo@beta agent object --command ./edit.json --session "$SESSION"
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
`--command` submits the JSON's `type`; the positional word is only a label.
|
|
10
|
+
Get clip IDs from `agent inspect` (`timeline.trackClipsMap`) or an import result.
|
|
11
|
+
Get object addresses and declared edit capabilities from `scene`/`object` results;
|
|
12
|
+
do not guess them. Dimensions and values use the authored scene's coordinates.
|
|
13
|
+
|
|
14
|
+
| Operation | JSON |
|
|
15
|
+
| --- | --- |
|
|
16
|
+
| Inspect timeline | `{ "type":"inspect" }` |
|
|
17
|
+
| Seek, seconds | `{ "type":"seek", "seconds":2 }` |
|
|
18
|
+
| Toggle playback | `{ "type":"play" }` |
|
|
19
|
+
| Pause | `{ "type":"pause" }` |
|
|
20
|
+
| Inspect a graphic scene | `{ "type":"scene", "clipId":"RETURNED_ID" }` |
|
|
21
|
+
| Set duration, seconds | `{ "type":"update", "clipId":"RETURNED_ID", "duration":8 }` |
|
|
22
|
+
| Replace an existing graphic's source | `{ "type":"import", "clipId":"RETURNED_ID", "name":"title.mjs", "source":"SOURCE_TEXT" }` |
|
|
23
|
+
| Move an editable object | `{ "type":"object", "clipId":"RETURNED_ID", "address":"RETURNED_ADDRESS", "transform":{ "position":{ "x":40, "y":20 } } }` |
|
|
24
|
+
|
|
25
|
+
`scene` returns a scene hit with its node list. To inspect a particular address,
|
|
26
|
+
include `address` on a `scene` command. `object` applies a transform; it requires
|
|
27
|
+
both `address` and `transform`. Supported fields depend on the renderer and the
|
|
28
|
+
object's declared capabilities. Pixi rotations use radians; Three.js coordinates
|
|
29
|
+
are scene units. Object transforms are distinct from timeline clip positioning.
|
|
30
|
+
|
|
31
|
+
`agent import --file` reads the named source into the command. To replace rather
|
|
32
|
+
than append, use a JSON command with the existing `clipId`. This interface does
|
|
33
|
+
not import a directory of relative assets; use Studio's HTML project directory
|
|
34
|
+
picker for that workflow. Keep stable addresses when replacing source so prior
|
|
35
|
+
edits remain attached to the intended objects.
|
|
36
|
+
|
|
37
|
+
`play` toggles playback rather than ensuring it is playing. Other commands pause
|
|
38
|
+
before executing, except `inspect`. A timed-out job may still finish: inspect
|
|
39
|
+
the current timeline before repeating an import, duration change or object edit.
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schema": 1,
|
|
3
|
+
"version": "0.1.0-beta.1",
|
|
4
|
+
"skills": [
|
|
5
|
+
{
|
|
6
|
+
"name": "vibevideo",
|
|
7
|
+
"hash": "e567029d2aac0017fe79d3e52a45a4cd0a41a79944bea4c927e34df6017b7604"
|
|
8
|
+
},
|
|
9
|
+
{
|
|
10
|
+
"name": "vibevideo-cli",
|
|
11
|
+
"hash": "06c479a36ba54ad9ecaa860760df10b987c11fcfe0706463dc9f3420e34de522"
|
|
12
|
+
}
|
|
13
|
+
]
|
|
14
|
+
}
|