Skip to content
creature-studioPublic

About

用 HTML 代码生成视频的确定性渲染框架:场景脚本、丰富效果库、一条命令导出 MP4

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

vidkit

用 HTML/JS 代码生成视频的通用框架:一行一个元素,一帧一个纯函数。 工作名 vidkit:改名只需改 package.json 的 name / vidkit.global 与本 README 标题(CLI 命令名在 package.json 的 bin)。

  • 确定性:每一帧 = render(t),不依赖真实时钟、不读 Math.random()(setup 阶段的随机数已被种子化)。任意跳帧、并行渲染、重复渲染结果一致。
  • 简单:vk.video() + vk.scene() + 元素工厂,写宣传片 / 数据讲解 / 竖屏短视频不需要写一行动画代码。
  • 效果丰富:42 个元素特效、44 个转场(均含别名;去重后 39 / 40)、19 个区块/图表、7 种质感、5 种背景、4 套主题、9 种画幅预设。
  • 可下沉:随时 scene.on(t => …)、vk.el(ctx => …)、scene.canvas()、scene.webgl() 写原生代码。
  • 可扩展:所有效果都是插件注册出来的,第三方插件与内置预设能力完全相同(vk.use(plugin))。
  • 离线:字体随包(均为 OFL 1.1),音效由 OfflineAudioContext 合成,渲染不联网。
  • 对 agent 友好:严格模式(未知名称报错 + did-you-mean + 文件:行号)、带参数 schema 的注册表(vk list、docs/api.json、docs/vk.d.ts、llms.txt)、确定性静态检查 vk lint、一次启动看全片的 vk peek(静帧 + 联系表 + peek.json 自动视觉检查)、--draft 草稿模式;工作流见 AGENTS.md。
  • 音频与节奏(Phase 2):vk analyze 节拍/强拍/段落/响度分析 → 画面卡点(提前一帧);vk align 中英文词级对齐 → 卡拉 OK 字幕与歌词 MV;vk tts 配音驱动场景时长;渲染时自动 ducking + −14 LUFS 响度归一;vk sync 实测音画同步。

目录

  1. 快速开始
  2. 架构
  3. 场景 API
  4. 预设目录
  5. 主题
  6. 画幅与安全区
  7. 字幕与音频
  8. 音乐、节奏与配音(Phase 2)
  9. 下沉到原生代码
  10. CLI
  11. 编写插件
  12. 开发与测试
  13. 路线图(Phase 3)
  14. 风格库(style packs)
  15. 镜头与动作(Phase 3)
  16. 动态图形套件(vk.mg)与运动模糊
  17. 3D:vk.three(three.js r186,可选)
  18. 面向 agent:严格模式、注册表、lint、peek、草稿
  19. 字体与素材许可

制作流程入口:快速制作与排版调优 · 横竖屏样板与分镜表


快速开始

依赖:Node ≥ 18、ffmpeg/ffprobe、Playwright Chromium(npx playwright install chromium,同时会装上默认捕获用的 chrome-headless-shell;没有时自动回退到 --capture screenshot)。

cd vidkit && npm install && npm run build   # 生成 dist/vidkit.js(单文件 IIFE)与 dist/vidkit.esm.js
npm link                                     # 可选:全局命令 vk
vk new hello.html --format 9:16 --theme bold # 生成模板
vk preview hello.html                        # 本地预览:热更新 + 进度条 + 场景列表(按 s 显示安全区)
vk lint hello.html                           # 确定性静态检查(render 闭包里的 Math.random / Date.now / 定时器 …,未知名称)
vk peek hello.html                           # 一次启动:低清静帧 + 联系表 + peek.json(版面 / 对比度 / 闪烁 / 确定性检查)
vk qa hello.html                             # 版面 QA(重叠 / 溢出 / 安全区 / 字幕 / 字体 / 空帧)
vk render hello.html -o hello.mp4 --srt      # 逐帧渲染 → H.264 MP4(+ SRT 字幕)

最小示例(一个 HTML 文件就是一条视频):

<script src="../dist/vidkit.js"></script>
<script>
vk.video({ format: '16:9', fps: 30, theme: 'tech-blue', transition: 'push-left:0.6' });

vk.scene('开场', 5, { bg: { type: 'grid' }, cap: 'Spark:AI coding agent 的启动器' }, [
  vk.hero('Spark', { cursor: true, at: .3 }),
  vk.sub('AI coding agent 的**启动器与配置中心**', { at: 1.2 }),
]);

vk.scene('数据', 6, { bg: 'light', transition: 'iris:0.7' }, [
  vk.h2('一年增长 ==6.5 倍==', { fx: 'words' }),
  vk.bar([['一月', 12], ['二月', 19], ['三月', 27]], { highlight: 2, source: '示例数据' }),
]);
</script>

示例(examples/)

文件 内容 输出
promo.html 16:9 开源项目宣传片(Spark 仓库真实信息) out/promo.mp4
explainer.html 16:9 数据讲解:全球 CO₂ 排放(Our World in Data 真实数据,data/co2.json) out/explainer.mp4
vertical.html 9:16 竖屏短视频 ~15s,128 BPM 卡点,大字动效,避让平台 UI out/vertical.mp4
mv.html 16:9 节拍同步歌词 MV:Kevin MacLeod《Voxel Revolution》(CC BY 4.0)+ TTS 人声;节拍/段落来自 vk analyze,歌词时间来自 vk align --separate,vk.lyricVideo() 一行生成(素材制作脚本 mv/make-song.mjs) out/mv.mp4
explainer-vo.html CO₂ 讲解的配音版:每个场景 vo: + dur:'auto',时长由 TTS 决定并吸附到背景音乐节拍,逐字高亮字幕,ducking + −14 LUFS out/explainer-vo.mp4
tadpole/tadpole.html 水墨动画短片《小蝌蚪找妈妈》(~126 s):ink 主题 + 宣纸质感 + 墨线滤镜,竖排书法片名/章节名 + 朱印,SVG 角色 rig(蝌蚪群、青蛙、鸭、金鱼、鹅、乌龟),多角色配音(6 种 edge-tts 音色),程序合成古琴/笛子配乐(tadpole/make-music.mjs,CC0)与水声/蛙鸣/鸭叫音效 out/tadpole.mp4
gl-ink-demo.html vk.gl WebGL 水墨特效演示(20 s):墨滴溅落与题字洇开、远山晕染成形 + 雾带、荷塘水墨化后期 + 水花/落花、剪纸窗花 out/gl-ink-demo.mp4
tadpole/tadpole-gl.html 《小蝌蚪找妈妈》片头的 GL 版(原片未改) out/tadpole-gl.mp4
nezha/nezha.html 水墨神话短片《哪吒闹海》(骨骼版):作者手绘哪吒 SVG 接入 vk.rig(idle / float / attack 片段 + IK 出手),程序化混天绫、龙与海浪;nezha.html 为早期非骨骼版,nezha-ref/ 为原始 rig 演示 out/nezha-rig.mp4
wusong/wusong.html 上美厂风格剪纸动画短片《武松打虎》(~69 s):剪纸角色 rig(武松、吊睛白额虎,lib/*-rig.js)+ 水墨景阳冈(lib/jingyang.js),vk.gl 墨晕片名/落叶/木屑,edge-tts 说书旁白(YunjianNeural),代码合成京剧锣鼓(四击头 / 冲头 / 急急风,lib/papercut.js) out/wusong.mp4
gallery.html FX Gallery 活文档:每个预设一小段 + 名称 + 生成它的那行代码 out/gallery.mp4
plugin-demo.html 插件示例(plugins/hello-plugin.js) —
styles/<id>/preview.html 风格库:10 个风格包(含需要 vidkit-three.js 的 three-tech)各自的 ~5 s 同一样片(片名 + 角色 + 特效 + 转场);vk style gallery 生成画廊页 out/styles/<id>.mp4 · out/styles/index.html
kite-papercut/ · kite-ink/ vk make 生成的短片:同一个故事 stories/kite.md(3 场景、旁白 + 两个角色对白)分别用 papercut 与 ink 风格生成 out/kite-papercut.mp4 · out/kite-ink.mp4
reel/reel.html 15 s / 128 BPM 动态海报 reel(8 个一小节场景):vk.mg 全套——彩条覆盖转场卡在小节线、冲击波环 / 速度线 / 放射线 / 白闪、字母砸落挤压拉伸、汉字 slam + 回声残影 + 硬投影、逐拍形变、点阵波浪背景、数据弹性柱、手机里的 UI 微交互、半拍关键词快切、汇聚收束 logo、HUD;子帧运动模糊 + 合成鼓组。out/reel-original.mp4 为参考原片逐帧渲染,out/reel-compare.png 为对照表 out/reel.mp4
wusong/wusong-v2-scene.html 《武松打虎》打斗两场重做(一棒劈下 · 骑虎挥拳):镜头系统(近景/跟拍/打击推近、头部不出画)、脚步锁定的走路、竖直劈棒、可见的拳、帽带跟随运动(原片 wusong.html 未改) out/wusong-v2-scene.mp4
three-basics.html vk.three 入门(11 s):粒子星系 → 文字、耳机转台 + 灯条扫光、手机 orbit + 景深(需 dist/vidkit-three.js) —
agent-test/agent-test.html agent 自测片(10 s):只按 llms.txt + AGENTS.md 写成——tech 风格 + 原生 canvas 星空 + 小的 vk.three 环面结,lint → peek 循环(见面向 agent) out/agent-test.mp4 · out/agent-test-sheet.png
three-promo/three-promo.html 3D 产品宣传片(24 s,1080p,虚构耳机 LUMEN Buds):粒子 logo 组装、转台主镜头 + 扫光、CatmullRom 穿梭、三色并排、crane 片尾,bars 覆盖转场,合成器铺底 + edge-tts 中文旁白,运动模糊 out/three-promo.mp4 · out/three-promo-sheet.png
ink-landscape/ink-landscape.html 水墨 3D 山水(15.5 s):vk.three.terrain + text3d(中文子集)+ look:'ink',不含任何水墨专用 3D 代码 out/ink-landscape.mp4 · out/ink-landscape-sheet.png
popup-book/popup-book.html 剪纸立体书(19 s):diorama popup(开书、纸片立起、翻页、昼夜)+ papercut 灯箱尾声 + look:'papercut' out/popup-book.mp4 · out/popup-book-sheet.png
three-character.html GLB 角色(10.6 s):RobotExpressive(CC0)mixer 时间线混合片段 + look:'comic' —

npm run examples 会依次对每个示例做 QA、渲染 MP4+SRT、生成联系表与静帧到 out/。


快速制作与排版调优

推荐顺序:分镜表 → 第一幕与文字最密的一幕 → 单帧调优 → 样板 Peek → 扩展全片 → 完整 Peek → 渲染。 可复制的 workflow-starter 提供横屏、竖屏和可选旁白页,包含本地 SVG 配图,无需先生成图片。

先建立文案与版面的标尺

  • 分镜表把屏幕标题、字幕、旁白分开写;一幕一个重点。先固定样板的字体、字号、边距和间距,再扩展全片。
  • 中文字幕以横屏每段 18–22 字、竖屏 12–14 字起草,正文以 720p 基准 24–30px 起步。字数只是预算,实际宽度受字体、内边距、中英文混排影响。
  • 长句按“分段或精简 → 调整容器和布局 → 小幅调字号”处理。无旁白时 cap: ['第一段', '第二段'] 会均分场景时间;有旁白时用 TTS 自动字幕,需要精确同步时使用带时间的字幕。
  • 横屏字幕默认单行,直接改 CSS 换行还会触发 caption-wraps。不要把整段解说放进标题或卡片。
  • 画幅以 v.W / v.H / v.safe 为准:当前 16:9 为 1280×720,安全边距上/右/下/左为 56/80/64/80;9:16 为 1080×1920,边距为 250/160/460/72。元素工厂的数值尺寸按 720p 基准缩放,CSS 像素字符串不缩放。

用 Studio 单帧循环调整,不必每次生成联系表

从仓库根目录运行(未全局安装时,把 vk 换成 node bin/vk.mjs):

vk studio examples/workflow-starter/landscape.html --no-open

保持 Studio 运行,在另一个终端请求画面;默认 UI 地址为 http://127.0.0.1:3210/__studio/。

curl -s 'http://127.0.0.1:3210/api/state?wait=1'
curl -s 'http://127.0.0.1:3210/api/frame?t=0&scale=.5&save=1'
curl -s 'http://127.0.0.1:3210/api/frame?t=2.5&scale=.5&save=1'
curl -s 'http://127.0.0.1:3210/api/frame?t=7.1&scale=1&save=1'

save=1 返回图片路径;Agent 读取该文件审视画面。编辑后重新请求修改场景:半尺寸看构图,原尺寸看小字与混排。检查首帧、入场中段、稳定画面和转场中点。Studio 支持实时重载;无 Studio 时可用:

vk stills examples/workflow-starter/landscape.html --at 0,0.5,2.5,4.8,7.1 -o out/workflow-starter/stills

样板和全片完成时分别运行 vk lint、完整 vk peek,查看 peek.json 和联系表。局部截图不替代完整验收;记录 Peek 次数、timings.total 和警告解释作为基线,不预设提速比例。

blank-first-frame、outside-safe-area 在 Peek 中是警告;稳定画面的溢出、空白可能是错误。首幕让一个有意义的标题或图像 at: 0, fx: false 即可,其余正常入场;纯色底仍可能被判为均匀画面。刻意淡入可以保留并说明原因。

复用布局、图片与按需旁白

非对称排版先组合 row/col/grid/split 和 pos。样板演示非等宽图文、主图加信息卡、上下分区;复杂 3D/Canvas 与文字先约定区域和共同时间,再制作层内效果。字幕单独预留空间。

图片放在作品自己的 assets/,记录来源与许可,使用相对路径。vk.image() 默认已有 Ken Burns 运镜,先确认裁切,再调 from/to/fit;kenburns: false 可以关闭。

旁白在项目开始时确定。先跑 vk doctor,再验证一条短句;基本 Edge TTS 可以独立于音频分析/对齐包工作。需要补齐工具链时使用 bash tools/setup-audio.sh --light:它跳过可选重型工具的安装步骤,但仍安装基础音频依赖,并不等于仅安装 TTS。

vk doctor
vk tts examples/workflow-starter/voice.html
vk tts examples/workflow-starter/voice.html  # 相同文本与语音参数复用缓存
vk peek examples/workflow-starter/voice.html
vk render examples/workflow-starter/voice.html -o out/workflow-starter/voice.mp4 --srt

Edge TTS 生成需要联网。文案确认后生成旁白,再锁定场景时长与动作;改文案后重跑 TTS。vo + 'auto' 使用语音时长,voice.maxChars 控制自动字幕分段。Edge 词边界可直接供字幕使用;只有外部音频或缺少/不足的时间信息才需要 vk align。生成后的本地音频可离线复用;vk sync 是额外同步诊断,需要相应分析依赖。

最后完整 Peek 达到 ok: true,逐条解释剩余警告,再渲染 MP4、生成最终联系表并用 ffprobe 检查时长和分辨率;交付 MP4、联系表、HTML 路径和 SRT。QA 帮助发现技术问题,画面层次与阅读舒适度仍需看图判断。

架构

┌──────────────────────────── 4. 创作 API(authoring/)───────────────────────────┐
│ vk.video / vk.scene / vk.title … vk.bar … 主题 · 画幅 + 安全区 · 字幕轨 · md 标记 │
├──────────────────────────── 3. 效果预设(fx/)──────────────────────────────────┤
│ text · transitions · svg · charts · blocks · textures · backgrounds · shapes     │
│ (全部通过 registry 注册 = 插件)                                                 │
├──────────────────────────── 2. 渲染层(layers/ + DOM)──────────────────────────┤
│ DOM/CSS 层(文字、布局)· Canvas2D 层(纹理/粒子)· WebGL 层(片元着色器,Phase 3)│
├──────────────────────────── 1. 核心(core/)────────────────────────────────────┤
│ render(t) · ease · timeline/tween · stagger · camera · seeded random · BeatGrid   │
│ scene graph(重叠/转场槽位)· plugin registry + hooks                             │
└──────────────────────────────────────────────────────────────────────────────────┘
  runtime/:注入 CSS、预览播放器、页内 QA、静态层缓存   cli/:headless shell BeginFrame 逐帧捕获 → ffmpeg
vidkit/
├─ package.json          name / bin(vk) / scripts
├─ bin/vk.mjs            CLI 入口
├─ AGENTS.md · llms.txt    agent 工作流 / 简明指南(llms.txt 由 npm run docs 生成)
├─ docs/                 api.json(完整注册表 + 参数 schema)· vk.d.ts(类型)——均由 npm run docs 生成
├─ cli/                  lint · lintcore(acorn AST) · peek · list · render · capture(beginframe/screenshot 捕获) · cdp(CDP pipe 客户端) · stills · contact · qa · preview · new · lib · analyze · align · tts · sync · doctor · mix(混音/ducking/loudnorm) · py
├─ tools/                vkaudio.py(Python 音频工具链)· setup-audio.sh · requirements-audio.txt
├─ src/
│  ├─ index.js           vk 对象(ES module 入口)
│  ├─ browser.js         IIFE 入口 → window.vk
│  ├─ meta/              注册表元数据:schemas.js(每个 fx/转场/质感/背景/区块/元素/three 模块的参数)· index.js(vk.list detail)
│  ├─ core/              strict(严格模式 / Math.random 守卫) · names(Levenshtein) · ease · random · time(BeatGrid) · stagger · interp · camera · timeline · plugin · scene · video
│  ├─ layers/            canvas.js · webgl.js
│  ├─ fx/                apply · text · transitions · svg · shapes · charts · blocks · textures · backgrounds · rhythm · lyrics
│  ├─ authoring/         api(元素工厂) · node(公共选项/md) · themes · formats · declarative(data-* 兼容)
│  ├─ audio/             score(离线音效合成) · music(节拍/包络/段落 MusicInfo) · words(对齐→字幕/卡拉 OK)
│  ├─ runtime/           css · preview · qa · bake(静态层缓存)
│  └─ three/             可选 3D 包入口 index · layer · post · math(纯函数) · loaders · env · materials · products · turntable · particles · cache(PMREM/粒子目标磁盘缓存)
│                        · look(NPR 链) · diorama · shapes · plate(shaderPlate) · text3d · sim · terrain/terrainmath(地形·地球) · model · mixer
├─ dist/                 vidkit.js(IIFE,~200 KB)· vidkit.esm.js · vidkit-three.js(可选 3D 包,含 three r186)
├─ vendor/               acorn 8(MIT,vk lint 用)· three r186 + addons(MIT)· Draco 解码器(Apache-2.0)· hdri/studio_loft_1k.hdr(Poly Haven CC0)· meshopt 解码器(MIT)· Natural Earth 陆地(公有领域);许可见 vendor/LICENSES.md
├─ fonts/                Noto Sans SC · JetBrains Mono · Archivo · Anton · Instrument Serif(OFL 1.1)
├─ examples/             promo · explainer · vertical · gallery · mv · explainer-vo · plugin-demo · data/ · assets/(music) · mv/ · plugins/
├─ scripts/              build · render-examples · list-presets · debug/probe 工具 · profile-render/profile-cpu · compare-capture/compare-video
├─ test/                core.test.mjs(缓动/时间/随机/节拍/插值)· audio.test.mjs(节拍网格/小节/提前一帧/词映射/混音表达式/分析器)· ink.test.mjs · capture.test.mjs(分块调度/捕获参数/烘焙辅助函数 + 浏览器往返)· agent.test.mjs(did-you-mean、lint 规则、文档是否最新、严格模式、vk list/lint/peek)
└─ out/                  渲染产物(git 忽略)

渲染流程:vk render 启动本地静态服务器 → 探测页面(时长 / 场景 / 音频,Playwright)→ N 个 chrome-headless-shell worker(默认 = CPU 核数)各自打开页面(?render=1),先执行一次静态层缓存(vk.bake)→ 帧按"连续车道 + 工作窃取"分块(默认 2 秒一块)分给 worker:对每帧调用 window.__seek(t)(内部就是 video.render(t))→ HeadlessExperimental.beginFrame 一次调用完成合成与截图(JPEG q95)→ 直接写入该块的 ffmpeg stdin(image2pipe,不落盘 PNG)编码为 H.264 分段(yuv420p、bt709)→ 分段 concat -c copy → 音频与帧并行准备:离线合成音效 WAV + 音乐(music/--audio)+ 配音(vk tts 生成的片段)→ ffmpeg 混音(ducking、两遍 loudnorm)→ mux(+faststart)→ 可选导出 SRT → ffprobe 校验 + blackdetect。详见下文渲染性能。

时间模型:场景在时间轴上首尾重叠,重叠长度 = 下一场景的转场时长(start = 上一场景结束 − 转场时长)。场景内所有时间都是场景本地秒(或 'b:8' 这样的节拍号,或 '+0.3' 表示相对上一个元素)。

渲染性能:捕获模式与静态层缓存

捕获模式(--capture)

模式 做法 适用
beginframe(默认) chrome-headless-shell 在 --enable-begin-frame-control 下运行(等价于 --deterministic-mode:--run-all-compositor-stages-before-draw、关闭 checker-imaging / 线程动画);每帧 render(t) 之后发一次 HeadlessExperimental.beginFrame({screenshot}),同一次调用里完成布局→绘制→合成→JPEG 编码并返回。没有 vsync / 帧率等待,没有 Playwright 往返。CDP 走 --remote-debugging-pipe(cli/cdp.mjs)。 所有页面(DOM / SVG / Canvas / WebGL)
screenshot 原来的路径:Playwright page.screenshot(),SwiftShader GL 合成。 回退 / 对照;找不到 headless shell 时自动使用
  • --gpu soft|swiftshader|off:soft(beginframe 默认)= 软件光栅 + 软件合成,WebGL 仍由 SwiftShader 提供;swiftshader(screenshot 默认)= 旧的 GL 合成;off = --disable-gpu(无 WebGL)。无 GPU 的机器上软件合成比 SwiftShader GL 合成快约 2–3 倍(tadpole 单帧截图 141–218 ms → ~60 ms)。
  • --workers N:beginframe 默认 = 可用 CPU 核数(优先使用 os.availableParallelism(),遵守进程 CPU 亲和性);screenshot 默认 min(4, 可用核数−1)。可显式覆盖。
  • --chunk 帧数:显式设置固定分块大小。beginframe 默认从 2 秒视频开始,根据上一块实际耗时调整,目标每块约 2 秒墙钟时间,范围为 1–10 秒视频。每块是一个独立的 H.264 分段,最后 concat -c copy;快的 worker 会从最慢的车道尾部"偷"一半。
  • --timing:打印每帧平均的 render(t) / 捕获 / ffmpeg 反压时间、分段数量和各阶段耗时。每个编码器默认线程数 = max(1, floor(可用核数 / (2 × workers))),给浏览器留出 CPU 预算;图片解码使用一个线程,滤镜使用相同的编码预算。--x264-threads n 可覆盖编码与滤镜预算,0 使用 FFmpeg 自动线程数。
  • 输出仍是逐帧精确的:帧 i 就是 render(i / fps),与旧路径逐帧对齐(错一帧的 PSNR 明显更差,见下表);音频路径未改(vk sync 结果一致)。
  • 容器/云主机注意:/dev/shm 很小(如 Docker 默认 64 MB)时 begin-frame 模式的渲染进程会崩溃,所以默认带 --disable-dev-shm-usage。可用 VK_CHROME=/path/to/chrome-headless-shell 指定浏览器、VK_CAPTURE=screenshot 全局切回旧路径。

静态层缓存(vk.bake)

feTurbulence / feDisplacementMap 墨线、feGaussianBlur 晕染、远山、宣纸纹理这类不随时间变化的内容,浏览器却会每帧重新跑滤镜(即使只是平移,亚像素位移也会触发重新光栅化)。vk.bake 在 __ready 之前把它们光栅化一次成位图:

vk.bake(svgEl)                        // 根 <svg>:内容换成一张 <image>(svg 元素本身、它的 CSS、你对它做的 transform 动画都保留)
vk.bake(g, { scale: 1.5, pad: 8 })    // svg 内部的 <g>/<path>/…:在自身用户坐标系里连同 filter 一起烘焙(滤镜区域自动计算),
                                      // 元素自身的 transform / opacity / clip-path / mask 仍然是活的,可以继续逐帧动画
<svg data-vk-bake> … </svg>           // 声明式写法(也接受 data-vk-static)
vk.video({ bake: false })             // 整片关闭;vk render / vk stills 的 --no-cache 同效(?cache=0)

规则与限制:被烘焙的子树必须是静态的(烘焙后不能再改其内部属性;元素自身的 transform/opacity 可以变);样式需来自属性 / 行内样式 / 可继承属性——文档 CSS 里针对后代的规则不会带进位图;引用了"抖动"滤镜(installInk({boil}))的内容会被自动跳过;位图按 devicePixelRatio × scale 光栅化,被放大很多倍的层请给更大的 scale;烘焙后的位图在亚像素平移时是重采样而非重新矢量光栅化(差异 < 1 灰阶)。每个 worker 各烘焙一次(tadpole:60 个层、19 MP、约 1.3 s)。window.__bake / vk.bakeStats 报告烘焙数量与耗时,vk render 会打印。

水墨套件已接入:texture: { rice } 的分形噪声纸纹只生成一次(一块噪声瓦片 → 全画幅 canvas 图案,内阴影单独一层保持在纸纹之上;rice: { cache: false } 回到旧实现);tadpole 的远山、中景、水面墨线、荷叶/荷花的 ink-wob 滤镜都已 vk.bake。wash 转场去掉了恒等的 brightness(1)。实测软件合成下 CSS brightness() 很便宜(mv 全画幅 ≈1.3 ms/帧,wash 转场 ≈1.7 ms/帧),真正贵的是模糊(wash ≈11 ms/帧)和 SVG 滤镜。

确定性检查:分块并行意味着帧的渲染顺序与时间顺序不同。如果某个值是上一帧留下的(例如一个 sc.on 写、另一个更早注册的 sc.on 读),它会滞后一帧,并在每个分块开头出错。vk qa 现在会比较"从 t−1/fps 走到 t"与"从别处跳到 t"两种情况下可见 DOM 的状态(--order-step 1 秒采样,0 关闭),不一致时给出 WARN 和具体元素/属性。tadpole 的光束亮度就是这样发现并修正的(改成 P.rayBoostAt(t) 纯函数)。

实测(8 核、无 GPU、Chrome for Testing 153 headless shell,1280×720 @30fps):

旧(screenshot,7 worker) 新(beginframe + 缓存,8 worker) 加速
tadpole 126.4 s / 3792 帧:帧阶段 385.0 s(9.9 fps) 49.4 s(76.7 fps) 7.8×
tadpole 总耗时(含音频、mux、blackdetect) 6 min 31 s 56 s 7.0×
其它示例 6 s 片段(180 帧,帧阶段 fps,旧路径 4 worker) promo 30.8 · explainer 30.2 · vertical(1080×1920) 12.9 · gallery 47.0 · mv 19.8 · explainer-vo 28.0 74.3 · 78.7 · 34.6 · 127.4 · 59.1 · 73.4 2.4–3.0× (短片段以浏览器启动/烘焙为主)

tadpole 每帧耗时构成(旧路径单 worker):render(t) JS + IPC ≈ 3–10 ms;截图 141–218 ms,其中约 29 ms 是等下一个 vsync/帧、其余是 SwiftShader GL 合成 + SVG 滤镜 + PNG/JPEG 编码。新路径(CPU 时间/帧,约 40–46 ms,之前 ≈ 59 ms):Viz 软件合成 ≈ 18–21 ms、浏览器主线程 JPEG 编码/base64 ≈ 10 ms、光栅 ≈ 6 ms、渲染进程主线程(render(t)、样式、布局)≈ 2–3 ms;x264(preset medium、CRF 18,宣纸颗粒很费码)≈ 34 ms/帧 CPU,约占总 CPU 的 40%。烘焙前 SVG 滤镜 ≈ 20 ms、远/中景重光栅 ≈ 17 ms、宣纸纹理 ≈ 8–13 ms。若可接受略低的编码质量,--preset fast 可再省约 30% 编码 CPU(SSIM 0.9899 → 0.9894)。

画质(scripts/compare-capture.mjs:同一时刻无损 PNG,旧路径无缓存 vs 新默认):tadpole 22 帧 SSIM 0.9942(最低 0.9939)、PSNR 47.7 dB(最低 46.3 dB),差异是抗锯齿与烘焙位图重采样,肉眼不可见。编码后每帧与各自无损源的 SSIM:新 0.9825、旧 0.9819(新分段编码不比旧差)。其它示例(每个 8 帧无损对比)SSIM:promo 0.9969、explainer 0.9957、vertical 0.9977、gallery 0.9996(WebGL 正常)、mv 0.9980、explainer-vo 0.9957,最低均 ≥ 0.995。vk sync(tadpole 字幕词时间 vs 成片重对齐):新 中位 −14.5 ms / 1 帧内 51.3%,旧 −15.0 ms / 51.3%,无变化。

工具:scripts/profile-render.mjs(截图路径分解)、scripts/profile-cpu.mjs(beginframe 每帧 CPU、--trace 输出 Chrome trace)、scripts/compare-capture.mjs(两种捕获设置的无损逐帧对比)、scripts/compare-video.mjs(两个 MP4 逐帧 SSIM/PSNR)。


场景 API

vk.video(cfg)

const v = vk.video({
  format: '16:9',            // '16:9' | '1080p' | '9:16' | '1:1' | '4:5' | 'vertical' …,或 w/h 自定
  fps: 30,
  theme: 'tech-blue',        // 或 { extends: 'bold', modes: { dark: { accent: '#00E0B0' } } }
  transition: 'fade:0.4',    // 默认转场(名称:时长)
  push: .03,                 // 默认每个场景的缓慢推镜
  texture: { grain: { amount: .05 }, vignette: .3 },   // 全片质感
  bpm: 128, beatOffset: 0,   // 节拍网格;或 beats: [0.52, 1.01, …] 显式节拍;或 beats: 'song.beats.json'(vk analyze 结果)
  music: 'song.mp3', voice: {…}, captions: 'x.align.json', lyrics: {…}, mix: { lufs: -14 },   // Phase 2,见下文
  autoSfx: true,             // 转场自动 whoosh
  score: [[1.2, 'kick', 1]], scoreOptions: { pad: [110, 165, 220], beatKick: 2 },
  captions: [[0.5, 2.5, '手动字幕']],
  motionBlur: { shutter: '1/40', samples: 4 },   // 子帧运动模糊(默认关;vk render 时生效,见 vk.mg 一节)
  cover: { colors: [...], n: 6, axis: 'alt' },     // 覆盖类转场 stripes / bars 的全片默认
  seed: 1, manual: false,    // manual:true 时需手动 v.start()
});

vk.scene(name, dur, opts?, nodes)

vk.scene('标题', 5, {
  bg: 'dark',                         // 'dark' | 'light' | 'accent'(主题色板模式)| CSS 颜色 | { type:'mesh' } | 数组叠加
  mode: 'dark',                       // 与 bg 背景组件搭配时指定文字色板
  transition: 'iris:0.7',             // 本场景入场转场,也可 { type, d, ease, focal:{x,y} }
  cap: '这一场的字幕',                 // 或 ['分句1', '分句2'] 均分时长,或 [[start, end, text], …]
  camera: [{ t: 0, x: 320, y: 360, s: 1.8 }, { t: 2, s: 1, ease: 'house' }],
  push: .08, shake: [{ t: 1, amp: 18, d: .6 }],
  texture: { rgb: { amount: 3 } },    // 本场景专属质感
  layout: 'center',                   // 'center' | 'left' | 'top' | 'bottom'
  sfx: false,                         // 关闭本场景自动转场音效
}, [ /* 元素节点 */ ]);

vk.scene('自动时长', 'auto', [ … ]);  // 时长 = 最后一个动画结束 + hold(默认 2.2s)
vk.scene('卡点', 'b:8', [ … ]);       // 8 拍

返回 Scene,可继续链式调用:.on(fn) .tween() .fx() .camera() .push() .shake() .beatZoom() .canvas() .webgl() .texture() .sfx() .add() .html()。

元素工厂与公共选项

工厂 默认 fx 说明
vk.title(text, o) letters 大标题
vk.h2(text, o) reveal 二级标题
vk.sub / text / small / label up / fade 副标题 / 正文 / 小字 / 眉标
vk.hero(text, {cursor, outline}) letters 字标(带光标 / 描边)
vk.stack(lines, {w}) stack 动态堆叠大字,每行自动撑满宽度
vk.row / col / grid / split(left, right, {ratio}) / spacer — 布局
vk.badge pop 胶囊标签
vk.html(str) / vk.svg(markup) / vk.el(ctx => Element) — / draw / — 原生逃生口

所有工厂共享选项:at(入场时间)、fx(特效名,可组合 'up blur',false 关闭)、d(时长)、ease、each(逐字/逐项间隔)、out(出场时间)+ outFx、sfx(入场音效)、size(数字 = 720p 基准像素,或 'h1'… 主题字号)、color、bg、weight、font(display|mono|sans|serif|condensed)、align、w/maxW/mt(0–1 为画面比例,>1 为像素)、pos:{x,y,right,bottom,anchor} 绝对定位、fixed(不跟随镜头)、class、id、style、on(el, local, p, t)。

文字内联标记(md):**强调色**、==荧光笔==(自动 highlight 扫过)、__下划线__(自动 underline 画出)、`代码`、\n 换行。markAt 控制标记动画时间。

数据:vk.json('data/x.json')(同源同步加载)或 vk.json('#inline-id')(<script type="application/json">)。


预设目录

完整清单可用 vk.list('fx' | 'transitions' | 'blocks' | 'textures' | 'backgrounds' | 'themes' | 'formats' | 'sounds') 查询;out/gallery.mp4 里每个预设都有演示与代码。

文字特效(fx)

名称 效果 片段
fade up down left right 淡入 / 方向滑入 vk.text('…', {fx:'up'})
scale pop zoom blur rise 缩放 / 弹出 / 放大 / 失焦 / 上浮+失焦 {fx:'pop'}、组合 {fx:'up blur'}
wipe wipe-left wipe-up wipe-down reveal clip-path 擦出 / 遮罩上推 {fx:'reveal'}
grow grow-y flip stretch 横向/纵向生长、翻转、字宽拉伸(Archivo wdth 轴) {fx:'stretch', font:'display'}
letters letters-fade letters-blur domino squash assemble wave 逐字:滑入 / 淡入 / 失焦 / 多米诺 / 挤压弹跳 / 四散汇聚 / 波浪 vk.title('…', {fx:'letters', each:.04})
words words-up 逐词弹出 / 逐词上推(` ` 手动分词)
type 打字机(预留最终宽度,光标) {fx:'type', cps:14}
scramble / decode 乱码解码 {fx:'scramble'}
count 数字滚动(千分位、小数、前后缀) vk.title('0', {fx:'count', to:2048, sep:','})
highlight / marker · underline 荧光笔扫过 · 下划线画出 vk.text('把 ==重点== 标出来')
swap 关键词换色 {fx:'swap', at:1}
stack 动态堆叠(每行撑满盒宽,交替方向入场) vk.stack(['KINETIC','TYPE'])
draw draw-fill/fill morph SVG 描边绘制 / 描边后填充 / 形状变形 见 SVG
slam echo drop letters-pop mask-rise hard-shadow 动态海报字(vk.mg,首次使用时注册):大比例+旋转+偏移砸入(echo:3 残影、shadow:[dx,dy,色] 硬投影、wobble 落定后摇摆)/ 回声残影放大入场 / 逐字砸落 + 挤压拉伸 / 逐字弹出 + bob / 逐字从遮罩线下升起 / 硬投影长出(可组合 'pop hard-shadow') vk.title('MOTION', {fx:'drop', shadow:[10,10,'#0008']})
none 无动画

转场(transition: 'name:秒')

类别 名称
基础 none fade crossfade dip(经黑场)flash(白闪)
方向(×4:-left -right -up -down) slide-*(新场景滑入)push-*(新推旧)whip-*(快甩+运动模糊)wipe-*(擦除;wipe = wipe-right)
缩放/模糊 zoom-in(=zoom)zoom-out blur zoom-through(旧场景放大 40× 穿过焦点,例如字母的孔)
遮罩形状 iris(=circle)iris-out shape-diamond shape-star shape-hexagon shape-triangle shape-heart shape-square shape-blob
分割 split(竖向对开)split-h(横向)split-open(旧场景从中间裂开)diagonal blinds(百叶窗)
故障 glitch(=slice,切片错位 + 色相抖动)
覆盖(vk.mg,画在两个场景之上,首次使用时注册) stripes(n 条彩条错峰滑入 outExpo / 滑出 inExpo,横竖交替,切点在转场正中)bars(彩条从一侧长满再向另一侧收走);选项 `{n, colors, axis:'x'

焦点可指定:transition: { type: 'iris', d: .7, focal: { x: 320, y: 360 } }。

SVG

vk.svg('<path d="M40 220 C 120 40, 220 40, 260 150"/>', { fx: 'draw', d: 1.6, viewBox: '0 0 500 300', w: 620 })
vk.svg('<rect …/><circle …/>', { fx: 'draw-fill', each: .25 })
vk.svg(`<path d="${vk.shapePath('circle', 150, 150, 120)}"/>`, {
  fx: 'morph', paths: ['circle', 'star', 'heart', 'square'].map(k => vk.shapePath(k, 150, 150, 120)), each: .8 })

逐拍形变:{fx:'morph', shapes:['circle','square','triangle','star'], beats:1, r:120, cx:150, cy:150}——每 beats 拍一步(outBack,提前一帧落拍;需 bpm),形状来自 vk.mg.shapeOutline(等弧长采样,可直接插值)。画布版(描边回声、内部镂空、每拍换底色、白闪)见 vk.mg.morphSeq。

vk.shapePath / shapePoints / shapePolygon(kind, cx, cy, r):circle、star、diamond、square、triangle、hexagon、polygon、heart、blob(固定顶点数,可直接互相插值)。路径不兼容时 morph 自动重采样为 n 个点。

图表(数据来自数组或 JSON)

名称 片段
vk.bar(data, o) vk.bar([['一月',12],…], {highlight:5, unit:'k', horizontal:false, colors:false, source:'示例数据'})
vk.line(data, o) vk.line(null, {series:[{name:'A', values:[…]}], labels:[…], area:true, dots:true})(多条线自动在右侧标注并防重叠)
vk.pie / vk.donut vk.donut([{label:'Go', value:42}, …], {r:150, center:'2024', centerLabel:'占比'})
vk.ticker(value, o) vk.ticker(98.6, {decimals:1, unit:'%', label:'可用性', from:0})
vk.ring(pct, o) vk.ring(72, {label:'完成度', r:120})
vk.table(spec, o) vk.table({header:['方案','耗时'], rows:[[…]], highlight:1}, {source:'…'})

数据格式:[[label, value], …] 或 [{label, value, color}, …]。图表若非真实数据,请在 source 标注"示例数据"。

区块

名称 片段
vk.hero vk.hero('Spark', {cursor:true, size:200})
vk.terminal(lines, o) vk.terminal(['$ npm i -g x', '✓ done'], {w:640}) — $ 行打字,其余淡入
vk.code(src, o) vk.code(src, {highlight:[3], w:760}) — 轻量语法着色、逐行出现
vk.cards(items, o) vk.cards([{icon, title, text, hl}], {cols:3})
vk.columns(items) vk.columns([{title, code, text}])
vk.kv(rows, o) vk.kv([['导入', 'cmd 说明'], …], {keyW:200})
vk.gantt(spec, o) vk.gantt({rows:[{label, start, end, hl}], range:[0,10], unit:'s'})
vk.diagram(spec, o) vk.diagram({w, h, nodes:[{id,x,y,w,h,label,sub,hl}], edges:[['a','b']]}) — 箭头自动绘制
vk.quote(text, o) vk.quote('…', {by:'作者'})
vk.image(src, o) vk.image('shot.png', {w:880, h:450, from:{s:1}, to:{s:1.2, x:-4}}) — Ken Burns
vk.device(content, o) vk.device('shot.png', {type:'browser', url:'…'})、{type:'phone'}、{type:'laptop'};content 也可以是节点数组
vk.split(left, right, o) 左文右演示,ratio:'5/7' 或 0.44
vk.cta(spec, o) vk.cta({title, sub, cmd, url, note})
vk.badge(text, o) vk.badge('NEW', {hl:true})

质感(texture: { name: opts },全片或单场景)

grain(胶片颗粒,24fps 刷新)· vignette(暗角)· flicker(亮度闪烁)· paper(纸纹)· halftone(半调网点)· scanlines(扫描线,roll)· rgb(RGB 错位,pulse 随节拍)。另外 vk render --grain 6 可在 ffmpeg 阶段加噪点。

背景(bg: { type, … })

gradient(spin)· mesh(流动渐变网格)· grid(drift)· dots(drift)· noise(动态噪声,speed)· dotwave(vk.mg:径向正弦点阵 + 每拍一圈脉冲环 + HSL 色相循环 + 文字留空 hole:{w,h,soft},canvas)。可数组叠加。

镜头

camera: [{t, x, y, s, r, ease}] 关键帧(平移/缩放/旋转;省略的 x/y 默认回到画面中心、s 为 1(与旧版一致);加 cameraHold: true / sc.camera(keys, {hold:true}) 则省略的 x/y/s/r 沿用上一帧)、shots: [...] 景别镜头表(见镜头与动作)、push: .08 缓推、shake: [{t, amp, d}] 抖动(24fps 量化,更像手持)、scene.beatZoom(.03) 随节拍脉冲缩放。

音效(sfx,离线合成)

kick bass tick hat pop chime whoosh riser snap(reel 风格包另装 reel-kick reel-hat reel-clap reel-whoosh reel-riser reel-blip reel-ping reel-click reel-pop reel-chord)—— vk.title('…', {sfx:'kick'}) 或 scene.sfx(1.2, 'pop', .6)。


主题

名称 气质 字体 色板(dark / light / accent)
tech-blue 科技蓝(沿用原工具包风格) Noto Sans SC 900 + JetBrains Mono 深蓝 #0B1020 / 灰白 #E8ECF4 / 品牌蓝 #3355FF
editorial 暖色杂志 / 报告 Instrument Serif 标题 + Noto Sans SC 米色纸 #F3ECE0 / 深棕 #1F1A17 / 砖红 #C8492B
bold 短视频大字(抖音/小红书) Archivo 900 + Anton 窄体 黑 / 明黄 #FFE600 / 玫红 #FF2E63
noir 黑白极简 + 红点缀 Archivo + Noto Sans SC 纯黑 / 纯白 / #FF3B30

每个主题包含:3 个色板模式、字号阶梯(display/h1/h2/h3/body/small/caption,按画面短边自动缩放)、图表调色板、字幕样式、默认缓动(house = cubic-bezier(.7,0,.2,1))。

自定义:vk.video({ theme: { extends: 'bold', modes: { dark: { accent: '#00E0B0' } } } }) 或 vk.register('themes', 'mine', {...})。


画幅与安全区

预设 尺寸 标题安全区(上/右/下/左) 说明
16:9(landscape) 1280×720 56 / 80 / 64 / 80 宣传片、讲解(--scale 1.5 出 1080p)
1080p 1920×1080 84 / 120 / 96 / 120 原生 1080p
9:16(vertical) 1080×1920 250 / 160 / 460 / 72 抖音 / 小红书:避开顶栏、右侧按钮栏、底部文案区
1:1(square) 1080×1080 80 / 80 / 96 / 80 信息流
4:5(portrait) 1080×1350 90 / 80 / 120 / 80 竖版海报

9:16 还定义了平台 UI 区域 top-bar、right-rail、bottom-info:vk qa 会检查文字是否落入这些区域,预览里按 s 可叠加显示。字幕默认位于底部文案区上方(captionBottom: 470),并限制在左右安全边之间。

场景内容默认排布在安全区内(.vk-content);需要出血的装饰元素用 pos 绝对定位或加 class: 'vk-bleed'。


字幕与音频

  • 每个场景写 cap,自动生成字幕轨(避开转场);vk render --srt 同时导出 .srt。
  • 词级时间(卡拉 OK):v.caption(start, end, text, [{w:'每', t:1.2}, …]),或直接由对齐 / TTS 结果生成(见下一节)。
  • 节拍网格:bpm 或 beats:[…](显式时间)或 beats:'song.beats.json'(分析结果);场景时长/入场时间可写 'b:8'(拍)、'm:4'(小节)。
  • 音效:页面定义的 score / sfx 在渲染时由 OfflineAudioContext 离线合成成 WAV,与音乐、配音一起混音。

音乐、节奏与配音(Phase 2)

Phase 2 把"声音"变成时间轴的一等公民:先离线分析音频 → 得到 JSON → 页面里用纯函数读取。渲染依然确定性(分析结果是静态文件,页面不做任何实时音频处理)。

安装音频工具链(一次)

tools/setup-audio.sh          # 在仓库内建 .venv(git 忽略):librosa · faster-whisper · stable-ts · edge-tts · piper · torch(CPU) · demucs · beat_this
tools/setup-audio.sh --light  # 不装 torch:节拍退化为 librosa(无神经网络 downbeat),无人声分离
vk doctor                     # 检查每个组件是否可用

Python ≥ 3.10(测试环境 3.13,纯 CPU)。模型首次使用时下载到 ~/.cache(whisper:HF Hub;beat_this / demucs:torch hub;piper 音色:~/.cache/vidkit/piper)。CLI 按 VK_PYTHON → .venv/bin/python → python3 的顺序找解释器。依赖清单见 tools/requirements-audio.txt,全部逻辑在 tools/vkaudio.py(可单独调用:python tools/vkaudio.py analyze|align|tts|separate|sync|doctor)。

工具选择与理由

任务 选用 理由 / 备选
节拍 + 强拍 beat_this(CPJKU, ISMIR 2024) 当前 SOTA 的节拍/强拍联合模型,CPU 上 40 秒歌曲 3–5 s;不需要 madmom(其在 Python 3.13 上无法安装)。无 torch 时退化为 librosa beat_track + 低频相位启发式估计强拍
onset / 响度 / 频段 / 段落 librosa 纯 Python 轮子、稳定;LUFS 用 ffmpeg ebur128 测
词级对齐 stable-ts align() + faster-whisper small(int8) 已知文本的强制对齐,中文逐字、英文逐词;比 whisperX 依赖少(无需 pyannote/wav2vec2 中文模型)
人声分离 demucs htdemucs(two-stem vocals) 歌曲先分离再对齐,误差明显下降;结果缓存在 ~/.cache/vidkit/demucs
TTS edge-tts(默认)/ piper(离线) edge-tts 中文音色自然、自带 WordBoundary 词级时间(需联网);piper 完全离线(zh_CN-huayan-medium),词时间由强制对齐补出
混音 ffmpeg(adelay/amix/volume 表达式/loudnorm 两遍) 无额外依赖,采样级精确

vk analyze:音乐分析

vk analyze song.mp3                 # → song.beats.json
vk analyze song.mp3 -o x.json --backend librosa --rate 50 --bands 8

输出(确定性,同一文件结果一致):

{ "vidkit": "beats", "bpm": 122.0, "meter": 4,
  "beats": [0.52, 1.01, …], "beatPos": [1,2,3,4,1,…], "downbeats": [0.52, 2.49, …],
  "onsets": […], "onsetStrength": […],
  "loudness": { "integrated": -13.9, "unit": "LUFS" },
  "envelope": { "rate": 50, "loud": […], "rms": […], "low": […], "mid": […], "high": […], "bands": [[…] × 8] },  // 0..1
  "sections": [{ "start": 0, "end": 15.7, "label": "A", "energy": .41 }, …],
  "tool": { "beats": "beat_this", … } }

节拍后处理:局部直线拟合去抖(--smooth 4)+ 与强 onset 的中位偏移对齐(--refine 40 ms,整体平移网格,不逐拍吸附;--snap 可逐拍吸附);BPM = 节拍时间的稳健线性拟合斜率。段落:小节同步 chroma+MFCC 的 Foote novelty + 响度跳变,边界落在强拍上。

在页面里使用音乐

vk.video({
  music: 'song.mp3',            // = audio;render 时自动混入(也可 --audio 覆盖)
  musicStart: 12.5,             // 从音乐第 12.5 秒开始用(所有节拍/包络时间自动平移)
  musicGain: .9,
  beats: 'song.beats.json',     // 或 [0.5, 1.0, …] 显式节拍;或 bpm:120
  lead: 1,                      // "提前一帧"规则:所有 pulse/hit/切点提前 1 帧(默认 1)
  snap: 'bar',                  // dur:'auto' 的场景切点吸附到 'beat' | 'bar' | 'b:2' | 'm:2'
});

vk.beat(16)          // 第 16 拍的时间(秒)          vk.measure(4)   // 第 4 小节第一拍(避免与柱状图 vk.bar 冲突)
vk.beatIndex(t)      // t 处的拍号(小数)            vk.measureIndex(t) / vk.beatInBar(t)
vk.onBeat(t, { unit: 'beat'|'bar'|'onset', k: 6, every: 1 })   // 脉冲 exp(-frac(beat)·k),拍点=1
vk.pulse(t) / vk.hit(t, t0) / vk.barPulse(t)
vk.energy(t, 'low'|'mid'|'high'|'loud'|0..7, smooth)             // 0..1 响度/频段包络(同样提前一帧)
vk.onsetHit(t, k)    // 最近一个 onset 的冲击包络(按强度加权)
vk.section(t)        // { start, end, label, energy };vk.sections() 全部段落
vk.quantize(t, 'beat'|'bar')

元素 / 场景级节奏参数(写 scale / rotate 独立 CSS 属性,与入场动画叠加而不冲突):

vk.title('DROP', { beat: { scale: .08, brightness: .3, unit: 'beat', k: 7, beats: [2, 4] } })  // 只在 2、4 拍脉冲
vk.hero('BASS',  { energy: { scale: [1, 1.12], brightness: [.8, 1.3], band: 'low', smooth: .08 } })
vk.scene('副歌', 'm:8', { beat: { scale: .02 }, energy: { brightness: [.85, 1.15] } }, [ … ])     // 整帧(镜头)调制
sc.onBeat(el, { scale: .1 });  sc.energize(el, { scale: [1, 1.2] });  sc.energyZoom(.04, 'low');  sc.beatZoom(.03, 'bar')

每帧舞台上还有 CSS 变量 --beat --bar --energy --low --mid --high,纯 CSS 也能跟节奏:style: 'opacity: calc(.5 + .5 * var(--beat))'。

自动卡点切镜:场景时长写 'b:8' / 'm:4' 时,切点精确落在网格上再减 lead 帧(从上一场景切入点算起,已考虑转场重叠);end: 'm:16' 指定绝对切点;dur:'auto' + snap 会把内容/配音决定的时长延长到下一个拍/小节。音效 v.sfx('m:4', 'kick') 也接受节拍时间,与画面共用同一套事件时间。

vk align:词级对齐(中文逐字 / 英文逐词)

vk align narration.wav --text script.txt            # 已知文本强制对齐(每行一句)
vk align song.m4a --lyrics lyrics.txt --separate    # 歌曲:先 demucs 分离人声,再对齐歌词
vk align talk.mp3 --lang en                          # 无文本:转写 + 词时间戳

输出 {vidkit:'align', lang, lines:[{start, end, text, words:[{w, t, end}]}]}:中文每个汉字一个单位(标点并入前一个字),英文每词一个单位。后处理 repair_and_refine:以句内最大的连续词簇为准修复离群词,再把句首词吸附到人声 onset(窗口 −0.3…+0.02 s);--no-refine 关闭。

接入字幕:

vk.video({ captions: 'talk.align.json', karaoke: 'sweep' })                // 'sweep' 逐字扫色 | 'on' 逐字点亮 | 'pop' 逐字弹跳
vk.video({ lyrics: { src: 'song.align.json', offset: 0, captions: false } })  // 歌词只做时间数据,由 lyricVideo 排版
vk.lyrics(cue, { style: 'pop'|'rise'|'karaoke'|'slam', beat: true, size: 110 })  // 逐词动态字(按词时间触发)
vk.spectrum({ bars: 32, h: 120, mirror: true })                             // 频谱条,由分析得到的 mel 频段驱动
vk.lyricLines                                                               // 当前页面的歌词行(getter)

歌词 MV 预设 vk.lyricVideo({ intro, outro, styles, sectionStyles, bgs, cut: 'bar'|'beat', cutTolerance: .15, spectrum, flash, zoom, energy }):每句歌词一个场景(同一小节内的句子合并),切点落在"首字之前最近的小节线";按段落轮换字体动效与背景;高能段落(能量高于中位数)自动加节拍缩放、白闪与频谱;所有歌词场景亮度跟随低频响度。

vk tts:配音驱动时长

vk.video({ voice: { manifest: 'page.vo.json', voice: 'zh-CN-YunxiNeural', rate: '+5%', lead: .5, tail: .8, maxChars: 16 }, karaoke: 'sweep' });
vk.scene('总量', 'auto', { vo: '2024 年,全球排放约 378 亿吨二氧化碳。', voLead: .4 }, [ … ]);
vk tts page.html                     # 为每个 vo: 合成音频 → page.vo/<hash>.mp3 + page.vo.json(按文本缓存,改一句只重合成一句)
vk tts page.html --backend piper     # 离线
vk tts --voices zh                   # 列出中文音色
vk tts --text "你好,世界" -o hi.mp3   # 单句
  • dur:'auto' 的场景时长 = voLead + 语音时长 + voTail(与动画结束时间取大者,再按 snap 吸附节拍)。

  • 字幕由 TTS 的词边界自动生成并切分(每条 ≤ maxChars 字,按标点断句),逐字卡拉 OK 高亮。

  • 未运行 vk tts 时页面仍可预览(按语速估计时长),vk qa 会报 VO missing;配音超出场景也会报 ISSUE。

  • 多角色配音:vo 可以是多句数组,每句可指定角色(voice.cast 里定义音色/语速/音高),逐句生成音频与字幕(字幕不重叠):

    vk.video({ voice: { manifest: 'p.vo.json', voice: 'zh-CN-XiaoxiaoNeural', gap: .3, cast: { tad: { voice: 'zh-CN-YunxiaNeural', rate: '+6%', pitch: '+10Hz' } } } });
    vk.scene('问路', 'auto', { vo: ['旁白一句。', ['tad', '妈妈!', { gap: .6 }], { who: 'duck', text: '嘎嘎!', at: 9 }] }, (sc) => {
      sc.voSegs;            // 构建节点前就已排好:[{text, at, dur, end, words, who}](场景内时间)
      sc.voAt(1); sc.voEndAt(1); sc.speaking(local, 'tad');   // 第 i 句起止、某角色此刻是否在说话(嘴型 0..1)
    });

    vk tts 按(音色, 语速, 音高)分组合成;默认音色的句子仍按原文本缓存(向后兼容)。

  • 常用中文音色(edge-tts):zh-CN-XiaoxiaoNeural(女,温暖)、zh-CN-YunxiNeural(男,讲解)、zh-CN-YunjianNeural(男,激昂)、zh-CN-XiaoyiNeural(女,活泼)、zh-CN-YunyangNeural(男,新闻)、zh-TW-HsiaoChenNeural、zh-HK-HiuMaanNeural;英文 en-US-AriaNeural / en-US-GuyNeural 等。piper:zh_CN-huayan-medium。

混音(vk render 自动完成)

音乐(按 musicStart 截取、配音处自动 ducking:attack 0.25 s / release 0.45 s、结尾淡出)+ 配音(adelay 采样级定位)+ 离线合成音效 → 两遍 loudnorm 到 −14 LUFS / −1.5 dBTP(linear=true,不压缩动态)。

vk.video({ mix: { lufs: -14, duck: -11, fadeOut: 2 } })     // duck = 配音时音乐衰减 dB
vk render page.html -o out.mp4 --srt [--lufs -16|off] [--duck -8] [--no-voice]
# 同时写出 out.audio.json(实测响度报告)与 out.words.json(带词时间的字幕,供 vk sync 使用)

只有 score 的旧页面保持原行为(峰值归一化、不做 loudnorm)。

vk sync:音画同步测量

vk sync out/mv.mp4 --beats examples/mv/song.beats.json      # 画面冲击帧(亮度跳变)vs 节拍 / 成片重新检测的 onset
vk sync out/explainer-vo.mp4 --words out/explainer-vo.words.json   # 对成片音频重新对齐,比较字幕词时间

报告帧误差直方图、within1Frame、late、onBeatOrOneFrameEarly 等。示例实测(30 fps,详见 out/*-sync.json):

成片 结果
out/mv.mp4 所有节拍驱动的画面冲击均落在拍点或提前 1 帧,无滞后;成片 onset 与分析节拍中位差 ≈ 0 ms
out/explainer-vo.mp4 字幕词时间 vs 成片重新对齐:中位 −3.5 ms,无系统偏移(残差为对齐器本身的噪声,p90 ≈ 170 ms)

限制

  • 纯 CPU;whisper-small 对齐的逐字误差约 50 ms(中位),快速说唱/密集歌词更差;可 --model medium 换精度。
  • stable-ts 的 silero VAD 需从 GitHub torch hub 下载,受速率限制影响,故固定 vad=False。
  • edge-tts 需联网、是微软在线服务(商用条款请自行确认);piper 中文音色 huayan 的数据集许可标注为 Unknown。
  • beat.brightness / energy.brightness 使用 CSS filter;软件合成下全画幅约 1–2 ms/帧,代价不大,但 blur() 类滤镜昂贵(≈10 ms/帧)。
  • 预览里的配音播放是近似的(HTML audio 跟随播放头),以渲染结果为准。

下沉到原生代码

vk.scene('自定义', 4, (sc, v) => {                 // nodes 也可以是函数:拿到 Scene 自己搭
  const el = sc.html('<div class="vk-h1">原生 DOM</div>', { flow: true });   // flow: 进入居中版式;单个元素直接返回,多个返回数组
  sc.tween(el, { t: .2, d: .6, from: { opacity: 0, y: 40 }, to: { opacity: 1, y: 0 }, ease: 'house' });
  sc.on((local, p, t) => { el.style.letterSpacing = (0.2 - 0.2 * p) + 'em'; });   // 每帧回调:只依赖时间
  sc.canvas((g, local, info) => {                   // Canvas2D 层:无状态粒子 = f(seed, t)
    for (let i = 0; i < 200; i++) { const a = local - vk.hash(i) * 2; if (a < 0) continue;
      g.fillRect(640 + Math.cos(i) * 300 * a, 360 + Math.sin(i) * 300 * a, 4, 4); }
  }, { z: 'back' });
  sc.webgl({ z: 'back', frag: 'void main(){ gl_FragColor = vec4(gl_FragCoord.xy/uRes, .5+.5*sin(uTime), 1.); }' });
});
vk.el(ctx => { /* 在节点列表里插入任意元素,ctx.scene / ctx.px / ctx.at(o) 可用 */ return document.createElement('div'); })

规则:渲染路径里只能依赖 t;随机用 vk.hash(i) / vk.rand(seed) / vk.noise1(x);需要状态的效果(物理、拖尾)请写成"从 0 积分到 t"的纯函数或预计算表。

兼容:原工具包 engine.js 风格的 data-* 声明式页面由 authoring/declarative.js 适配,可继续使用。


CLI

vk render  page.html -o out.mp4 [--fps 30] [--scale 2] [--format 16:9|9:16|1:1|4:5] [--audio music.m4a]
                                [--audio-offset s] [--grain 6] [--workers 4] [--from s --to s] [--crf 18]
                                [--preset medium] [--png | --quality 95] [--srt] [--no-score] [--score-gain-max 2] [--keep]
                                [--capture beginframe|screenshot] [--gpu soft|swiftshader|off] [--no-cache]
                                [--timing] [--chunk 帧数] [--x264-threads n]      (--workers 默认 = CPU 核数)
                                [--shutter 1/40 --samples 4 | --no-motion-blur]   子帧运动模糊(覆盖页面 vk.video({motionBlur}))
                                [--strict | --no-strict] [--draft]               未知名称报错(CLI 默认开)· 草稿画质(低分辨率、3D res .35/aa 1/无景深泛光)
vk lint    page.html [more.html …] [--json] [--quiet]          确定性静态检查 + 未知名称(文件:行:列 + 修复提示;有 error 时退出码 1)
vk peek    page.html [--at 0,2.5,5 | --every 1] [--draft] [--json] [-o dir] [--scale .5] [--no-determinism] [--no-flicker]
                                一次浏览器启动:静帧 + 带标注的联系表 + peek.json(有 error 时退出码 1)
vk list    [kind] [name] [--json]                              注册表:种类 → 名称 → 单个条目的参数 schema / 示例
vk stills  page.html [--at 1.5,4,9.2] [-o dir] [--scale 2] [--capture …] [--no-cache]   静帧 PNG(默认每个场景动画落定后的一帧)
vk contact page.html [-o sheet.png] [--times a,b | --settle] [--cols 4]   联系表(每场景 2 帧,或 --settle 1 帧)
vk qa      page.html [--sample 0.5] [--order-step 1] [--json=report.json] [--no-strict]   版面 QA + 渲染顺序确定性 + 可见文字快照(--json 同时写出每场落定帧 JPEG + summary)
vk preview page.html [--port 5173] [--host 0.0.0.0] [--dev]   开发服务器:热更新 + 进度条(--dev 同时监听 src/ 重建)
vk studio  [page.html | 目录] [--port 3210] [--no-open] [--draft] [--out-dir out/studio]   工作室(类 Remotion Studio,见下)
vk new     video.html [--format 9:16] [--theme bold]          生成模板(带 --story 时等同 vk make)
vk make    --style ink[,papercut.chars] --story story.md -o examples/<slug>/ [--tts] [--render]   故事 → 风格化配音短片页
vk style   list | sample | gallery | extract | new --from|--ref | mix a b | fork <id>
                                [--lufs -14|off] [--duck -10] [--no-voice]   ← render 的混音参数

# 3D / 资产
vk adopt   page.html|URL -o out.mp4 --duration s [--fps 30] [--size 1280x720] [--warmup 3] [--timers] [--canvas]
                                录制现成的实时(rAF)demo:虚拟时钟,只能顺序录制
vk asset   add <url|x.glb> [--name id] [--dir examples/assets/models] [--draco] [--licence id] [--author …] [--no-thumb]
           list | verify            压缩(meshopt/Draco)+ assets.lock.json + 转台缩略图;verify 校验哈希
vk font3d  font.ttf [-o x.json] [--chars "…" | --chars-file f.txt | --latin]   字体 → three typeface JSON

# 音频(Phase 2,需 tools/setup-audio.sh)
vk analyze music.mp3 [-o music.beats.json] [--backend auto|beat_this|librosa] [--rate 50] [--bands 8]
vk align   audio.wav [--text script.txt | --lyrics lyrics.txt] [--lang zh|en] [--model small] [--separate] [-o x.align.json]
vk tts     page.html [--voice zh-CN-YunxiNeural] [--backend edge|piper] [--rate +0%] [--force]   (--voices zh · --text "…" -o a.mp3)
vk sync    out.mp4 [--beats song.beats.json --music-start s] [--words out.words.json]
vk doctor

vk qa 检查项:文字重叠、文字溢出容器、出画、标题安全区、平台 UI 区(竖屏)、字幕宽度/换行/阅读速度(中文按 ≤9 字/秒)、字体是否加载、空白帧(含转场中点)、配音缺失 / 配音超出场景、音乐文件缺失、词时间非单调,并打印每个场景的可见文字快照,方便核对文案。以及 render(t) 是否依赖渲染顺序(seek-order)。ISSUE 为必须修,WARN 为建议检查(转场中点的 dip/flash 预期会报空白帧)。


vk studio:工作室(Studio)

vk studio                      # examples/ 下所有作品;浏览器打开 http://127.0.0.1:3210/__studio/
vk studio examples/reel/reel.html --port 3210 --no-open

本地网页工作台,布局参考 Remotion Studio(未复用其代码/素材):

  • 左栏:作品列表(扫描目录下调用 vk.video / vk.film 的页面,Ctrl+K 快速切换)+ 当前作品的场景列表。
  • 中间:实时预览。页面以 ?render=1&preview=1 载入 iframe,每一帧都是 window.__seek(t)——与 vk render 逐帧调用的是同一个确定性路径。 播放/暂停、逐帧、倍速、循环、In/Out 区间、安全区叠层、音乐 + 配音 + SFX 预听。
  • 底部时间线:场景块(转场重叠为斜纹)、节拍/小节(bpm / beats)、字幕、配音、音效提示点;拖动刻度尺即可 scrub,Ctrl+滚轮缩放。
  • 右栏检查器:时长/帧率/尺寸/风格/主题/运动模糊/节拍/音频;覆盖(fps、画幅、草稿,作为 URL 参数,与 CLI 一致,不改页面文件); 选中场景的运行时 JSON。vk make 生成的页面(内联 STORY JSON)可直接编辑并保存该场景 JSON(校验 + 备份到 out/studio/backup/)。
  • 顶栏:Draft / Strict 开关,Lint、Peek(联系表与问题列表,点击跳到对应时间)、Render(调用 vk render,进度条,完成后下载 MP4 / 内嵌播放)。
  • 素材工作区:内置角色和项目素材浏览,文件导入,名称/标签编辑,角色外观变体与动作预览,历史版本、固定版本调用代码、归档与恢复。资产保存在项目根目录的 assets/library/,角色版本包含风格模块快照。使用方法、API 与当前范围见 Studio 素材管理。
  • 绘本角色:vk.illustratedCharacter(sc, spec, options) 提供五头身附近的三种轮廓、八种动作、独立表情及本地部件扩展;素材库内置讲解员、探险者、工匠,扩展代码随版本快照保存。见 绘本角色接口与生成规范 和 完整样片。
  • 快捷键:Space 播放 · J/K/L · ←/→ 逐帧 · Shift+←/→ 1 秒 · ↑/↓ 场景 · I/O/X 区间 · +/−/0 时间线缩放 · R 渲染 · P peek · D 草稿 · ? 帮助。
  • 面向 agent 的 HTTP API:GET /api/state、POST /api/seek、GET /api/frame、POST /api/render、/api/jobs、SSE /api/events…… 完整列表见 GET /api 与 AGENTS.md(Studio API)。没有打开浏览器时由无头浏览器提供信息与静帧。
  • 实现:cli/studio.mjs(服务器 + API + 任务队列,复用 cli/lib.mjs 的静态服务器与风格包注入)+ studio/**/*.ts(TypeScript ES 模块 + CSS)+ src/assets/(共享类型、运行时、资产服务)。默认加载 npm run build 编译的模块,也可使用 Vite 开发或构建模式。 演示脚本:node scripts/studio-demo.mjs(截图 → out/studio-ui.png)。

按需播放与缓存:Studio 与直接打开 HTML 的播放器只初始化当前时间点需要的 3D 图层(转场重叠时准备两个场景),空闲时预加载播放方向上的相邻一个场景。HTML 和时间线先显示,未访问的场景不会提前加载 3D 素材、创建全尺寸画布或编译着色器。遇到尚未准备好的场景会显示加载提示,并暂停播放时钟与音频;快速拖动以最后一次选择的位置为准,也可以立即切回已准备好的场景。

同一个页面中,加载中的任务共用一个 Promise,准备完成的场景、模型与 GPU 资源保留供重播和跳回使用。刷新页面或热更新后重新创建场景;环境光贴图、粒子目标等仍使用既有的内容哈希磁盘缓存(~/.cache/vidkit)。这项优化减少启动和重复初始化的工作,每个动态画面仍由 HTML/JS 根据时间实时绘制。

预览模式下 window.__ready 表示公共资源准备完成,await window.__seek(t) 会继续等待目标场景。调试可用 window.__loadState() 查看各图层的状态,await window.__readyAll() 显式准备所有场景。vk render / peek 等捕获命令仍使用完整的 ?render=1 就绪流程;手动打开页面可用 ?preview=0 关闭按需初始化。启动对比:node scripts/profile-preview.mjs examples/three-promo/three-promo.html(可加 --draft;输出包含公共就绪、首帧、重复 seek 的耗时及已准备图层数)。

加载耗时日志:预览默认输出 [vidkit performance] 控制台日志,并使用 performance.mark/measure 标记各阶段:字体/图片、静态烘焙、公共等待、场景排队与初始化、3D 素材、粒子数据、环境贴图、着色器编译、预热及首帧。记录开始时间、结束时间、耗时(ms)、场景和错误;正在进行的阶段也能查看。console.table(window.__vkPerformance.snapshot()) 查看阶段,window.__vkPerformance.report() 导出完整报告(包含导航和资源请求的耗时、传输字节数)。浏览器 Performance 面板中的 User Timing 可找到 vidkit: 标记。

Studio 会自动将真实浏览器的阶段日志和首帧报告追加到 out/studio/performance.jsonl(自定义 --out-dir 时写到该目录)。每行带记录时间、作品路径和会话标识,刷新后历史仍保留;GET /api/state 返回 performanceFile。更新服务器代码后重启 vk studio 再刷新浏览器即可记录。scripts/profile-preview.mjs 的输出也包含完整阶段报告。捕获模式默认关闭这些详细日志,手动诊断可加 ?performance=1。父阶段包含子阶段,字体/图片可能并行,不能把所有阶段耗时直接相加;首帧计时指绘制完成,不包含浏览器实际呈现到屏幕的等待。

编写插件

插件可以是对象或函数,注册的效果与内置预设完全平级:

vk.use({
  name: 'hello',
  fx: {
    tilt: { from: { opacity: 0, transform: 'rotate(-8deg) translateY(30px)' }, to: { opacity: 1, transform: 'none' }, ease: 'spring' },
    neon: (el, o, api) => {                       // 函数型:自己安排 tween / 每帧函数
      api.tween(el, { t: o.t, d: .5, from: { opacity: 0 }, to: { opacity: 1 } });
      api.fn(el, local => { el.style.textShadow = `0 0 ${12 + 8 * Math.sin(local * 9)}px var(--accent)`; });
    },
  },
  transitions: { 'spin-in': p => ({ in: { opacity: p, transform: `rotate(${(1 - p) * -90}deg)` }, out: { opacity: 1 - p } }) },
  textures: { tint: (video, o) => { const el = document.createElement('div'); /* … */ video.stage.appendChild(el); return { el, update(t) {} }; } },
  backgrounds: { stripes: (scene, o, video) => ({ el, update(local) {} }) },
  blocks: { myChart: (data, o) => vk.node(o, function myChart(ctx) { /* → Element */ }) },   // 暴露为 vk.myChart
  sounds: { blip: (kit, t, gain) => kit.tone(t, 'square', 880, 440, .08, .3 * gain) },
  layers: { /* 新渲染层类型,Phase 3 的 rig/particles 就从这里接入 */ },
  hooks: { init(video) {}, frame(t, video) {}, qa(report, video) {} },
});
// 或函数形式:vk.use((vk, opts) => { vk.register('fx', 'x', …) }, opts)

签名约定:

种类 签名
fx (el, o, api) => void,或 {from, to, ease, origin, instant} 对象(可与其它对象预设组合);api = {scene, video, tween, fn, after(fontsLoaded), beats, fps, exit}
transitions (p, ctx) => ({in, out, under, flash, flashColor}),p 为缓动后的 0–1;in/out 为作用于新/旧场景的样式
textures (video, opts) => ({el?, draw?(ctx, t, info), update?(t)})
backgrounds (scene, opts, video) => ({el, update?(local)})
blocks (...args) => Node(用 vk.node(o, build, defaultFx) 创建)

元数据(vk list / 文档 / 严格模式的名称表都会用到):vk.register('fx', 'tilt', impl, { description, params: { amount: 'number|1|0..3|强度' }, example }),或 impl.meta = {…},或 vk.use({ …, meta: { fx: { tilt: {…} } } });不写时从函数源码里推断 o.x || 默认值 形式的参数。vk lint 会读页面里的 vk.use / vk.register,插件注册的名字不会被当成未知名称。

完整可运行示例:examples/plugins/hello-plugin.js + examples/plugin-demo.html。


开发与测试

Studio 客户端源码现在全部位于 studio/*.ts。核心的 time、ease、random、interp、stagger、timeline、resources 和运行时 performance 也已实际迁移为 .ts,由 tsc --noEmit 严格检查;其余源码仍按 JS 模块逐步迁移。

构建生成 lib/ 下的 ESM JS 与核心类型声明,以及供 CLI 使用的 lib/studio/collect.js。Studio 前端由 Vite 直接加载 studio/ 中的 TypeScript 源码。dist/vidkit.js 和可选 3D 包继续由 esbuild 生成;npm run build 会先生成核心 .d.ts,源码导入中的 .js 扩展名表示编译后的模块路径。

Studio 统一使用 Vite,支持热更新,需要 Node 20.19+ 或 22.12+;其他 CLI 命令继续支持 Node ≥18。直接运行 vk studio 即可,不再提供 --dev / --built 模式。

npm run typecheck                            # 类型检查,包含合法调用与预期错误样例
npm run build                                # 核心类型声明、ESM 模块、元数据采集函数和浏览器包
npm run dev:studio                           # Vite Studio + 现有 API,默认不自动打开浏览器
node bin/vk.mjs studio page.html              # 为指定作品启动 Vite Studio
npm run dev:video                            # 多文件 TS 创作示例
npm run build:video                          # 检查类型、构建固定产物并 lint
node bin/vk.mjs render out/typescript/index.html -o out/typescript.mp4
npm run check                               # 类型、核心/TS 示例构建、文档同步和测试

TS 视频示例见 examples/typescript/。正式渲染使用构建后的本地 HTML;场景逻辑热更新重建页面,避免重复注册。vk lint 会遍历 JS 的本地 import/re-export 和字面量动态 import,处理循环依赖并收集插件名称;它目前不直接解析 TS,也不证明跨模块调用链的确定性。

npm run build        # esbuild → dist/vidkit.js(IIFE, window.vk)+ dist/vidkit.esm.js
npm test             # node --test:缓动端点/单调性、cubic-bezier 解析、stagger、BeatGrid(小节/提前一帧/网格切点)、种子随机、插值、代码高亮、词映射/字幕切分、混音表达式、分块调度(每帧恰好一次/工作窃取)、捕获参数、滤镜区域/引用收集,以及一个真实浏览器往返(beginframe vs screenshot、烘焙 vs 不烘焙 SSIM ≥ 0.99、同一 t 帧字节一致);有 .venv 时额外跑 click-track 分析测试
npm run examples     # 渲染全部示例到 out/
npm run docs         # 由注册表生成 llms.txt · docs/api.json · docs/vk.d.ts(改了预设/schema 后先 npm run build 再跑;测试会检查它们是否最新)
node scripts/list-presets.mjs   # 打印已注册预设(同步本文档)
node scripts/debug-page.mjs /abs/page.html   # 打印页面报错与 console

ES module 用法:import vk from 'vidkit' 或 import { vk } from 'vidkit',包会自动提供类型声明;原来的 vidkit/src/index.js 路径通过 exports 映射到 lib/index.js。迁移后的核心子模块也提供生成的 .d.ts。运行时需要浏览器环境;字体路径通过 vk._setEnv({ base }) 指定。公共配置类型可用接口合并扩展。


路线图

Phase 2 · 音频与节奏 ✅(v0.2.0)

已完成:vk analyze / vk align / vk tts / vk sync、节奏 API、卡拉 OK 字幕、歌词 MV 预设、配音驱动时长、混音与响度归一(见音乐、节奏与配音)。后续可做:真人歌曲的多轨(stem)驱动、whisper medium/large 精度模式、voice 插件种类(接入更多 TTS 后端)、实时预览中的波形刷。

Phase 3 · 角色与高级渲染

  • 角色 rig:registry.layers 新增 SVG/Canvas 骨骼层,关节关键帧走现有 timeline(attr: / --var 插值已就绪)。
  • 手绘 boil:vk.boil(t, rate) 已在 core/random 中提供(返回按 8–12fps 步进的帧号,作为 vk.hash 的种子让线条抖动),Phase 3 配合 SVG filter / 路径扰动做成预设。
  • 粒子:Canvas2D 层 + 无状态粒子范式(见 gallery canvas2d · particles),后续封装 particles 预设(发射器/力场,从 0 积分到 t)。
  • WebGL 着色器层:scene.webgl({frag, uniforms: (local, info) => ({…})}) 已可运行(uTime/uRes/uBeat/uProgress);Phase 3 增加多 pass、纹理输入(把 DOM 场景作为纹理)与着色器转场。
  • vk.gl 水墨 WebGL 层 ✅:多 pass 着色器(墨晕、水墨化后期、宣纸、雾带)、确定性粒子、线条 boil、剪纸滤镜(见WebGL 特效)。后续:把 DOM 场景整体作为纹理的着色器转场。剪纸角色 rig(上美厂风格)见 examples/wusong/。

水墨套件(ink,Phase 3 预览)

参照《三个和尚》式的水墨动画语言,src/fx/ink.js 提供:

  • 主题 theme: 'ink'(宣纸 #e4e5d8 / 墨 #1f2529 / 朱砂 #b5342a;马善政毛笔字 + 思源宋体;字幕条为宣纸底、红色左边框)与质感 texture: { rice: {} }(分形噪声纸纹 multiply + 暗角)。
  • vk.installInk(video, { boil }) 注入 SVG 滤镜:ink-line(墨线抖动)、ink-wob、ink-wash(晕染)、ink-far(远山)、ink-bleed(湿笔洇开)、ink-dry(枯笔)。
  • 区块:vk.vtitle('片名', { sub, seal }) 竖排书法片名 + 印章,vk.chapter('春水', { no: '一' }) 角落竖排章节名,vk.seal、vk.endcard、vk.credits。
  • 转场:ink(墨滴晕开遮罩,可设焦点 x/y)、wash(模糊交叉淡化);特效:ink / brush / brush-x / stamp。
  • 几何与 rig 工具:vk.brushPath(points, width|fn)(笔触轮廓)、vk.sampleLine(fn, n)、vk.attr(el, {...})(带缓存的 SVG 属性写入);关键帧助手 vk.bump / plat / hold / inRanges / smooth01 / kfSpline(按时间参数化的 Catmull-Rom)。
  • 纯 DSP 合成(vk.synth,Node 与页面通用、确定性):pluck(Karplus–Strong 古琴/琵琶,含滑音/吟猱)、flute、drop、bubbles、splash、croak、quack、woodfish、gong + reverb、mixStereo、penta(五声音阶)、wavBytes。同名 sfx 可直接用:sc.sfx(t, 'croak', .8, 480)。

完整示例:examples/tadpole/(lib/pond.js 池塘场景、lib/rigs.js 角色、lib/school.js 蝌蚪群)。

骨骼角色(vk.rig,src/fx/rig.js)

数据定义的骨骼层级 + 纯函数姿态(任意 t 可直接 seek,vk qa 顺序检查通过):

const rig = vk.rig({ root: g, bones: [{ id: 'torso' }, { id: 'upperArmR', parent: 'shoulderR' }, { id: 'lowerArmR', parent: 'upperArmR', x: 74, y: 4 }, …],
  clips: { idle: t => ({ upperArmL: 145 + 5 * Math.sin(t), 'root.y': 4 * Math.sin(2 * t), 'armR.tx': 205, 'armR.ty': -145 }) },
  ik: { armR: { chain: ['upperArmR', 'lowerArmR', 'handR'], bend: 1 } } });          // 元素:[data-bone="id"]
const act = rig.play([{ at: 0, clip: 'idle' }, { at: 3.8, clip: 'attack', blend: .4 }],
  { ik: { armR: t => [x, y] /* 世界坐标,或关键帧 [[t,[x,y]],…] */ }, ikMix: { armR: [[3.8, 0], [4.4, 1]] } });
sc.on(l => act.render(l, { x: 640, y: 380, scale: .55, flip: -1 }));
  • 姿态 = 普通对象:骨骼id 角度(叠加在静止旋转上)、id.x / id.y / id.s、root.x / root.y / root.rot(根内运动:起伏、倾身)、<ik>.tx / .ty / .w(片段自带的 IK 目标与权重,根局部坐标),其余为自由通道(如 energy)。
  • IK 在链根的父坐标系里用矩阵求解(不用 getCTM,考虑根的旋转/缩放/镜像与骨骼偏移);rig.point(bone, x, y, pose, root) 求任意骨骼点的世界坐标(例如乾坤圈出手位置)。
  • rig.sample(track, t) 片段交叉淡化(可链式),vk.rig.blink(t, {period, dur})、vk.rig.solve2BoneIK、vk.rig.blend、vk.rig.mat;rig.debug(true) 显示骨骼调试层(默认关)。
  • 示例:examples/nezha/(lib/nezha-rig.js 用作者手绘的哪吒 SVG:idle / float / attack 片段 + brace / bow / dive / throw,程序化混天绫随 energy 与方向摆动)。

WebGL 特效(vk.gl,src/fx/gl/)

一个按时间纯函数渲染的 WebGL 层:水墨晕染、SVG 水墨化后期、着色器宣纸、确定性粒子、线条 boil、剪纸滤镜。没有 requestAnimationFrame / performance.now / Math.random,噪声全部带种子;每个层在 render(t) 里同步重绘(或在缓存键不变时保留像素),所以任意 seek 顺序得到同一帧(vk qa 会对每个 canvas.vk-gl 做像素哈希比对)。

sc.gl([                                                              // 场景层(v.gl([...]) = 全片层)
  vk.gl.paper(),                                                     // 着色器宣纸(云絮 + 纤维 + 杂点 + 暗角)
  vk.gl.inkBleed({ src: vk.gl.text('水墨丹青', { x: 1010, y: 104, size: 118, vertical: true }),
                   at: 1.5, draw: .9, dur: 3, spread: 8, wipe: { dir: 'down', dur: 1.7 } }),   // 写字 + 洇开
  vk.gl.particles({ preset: 'splatter', burst: [{ t: 2, n: 70 }], x: 460, y: 380 }),          // 墨点飞溅
], { rect: [0, 0, 1280, 720], scale: 1, z: 'front' | 'back', blend: 'multiply', opacity });

层选项:rect(只渲染这块区域,性能关键)、scale(内部分辨率倍数,如 .75)、z: 'back'(插到背景之后、内容之下)、blend(CSS mix-blend-mode)、opacity、class。返回的层有 .el(2D canvas,可移动到任意 DOM 位置,例如放进池塘根节点里某个 SVG 之上)。

遮罩/颜色来源(场景像素坐标):vk.gl.text(str, {x, y, size, font, vertical, lead, tracking})、vk.gl.path(d | [d…], {fill, gradient, stroke, transform})、vk.gl.image(img, rect)、vk.gl.draw((g, local) => …, {static, key})、vk.gl.svg(el, {offset, exclude, static})(把活的 SVG 子树画到 canvas:path/rect/circle/ellipse/line/poly/image/text/use、描边虚线、线性/径向渐变、透明度;忽略 SVG filter——由 GL 效果代替)。static 来源只在字体加载后画一次并保留 GPU 金字塔。

效果:

效果 作用 主要选项
paper(o) 宣纸(mode:'overlay' 输出 multiply 图,配合层 blend:'multiply' 叠在任意场景上) color amount fibres vignette specks seed
inkBleed(o) 墨晕:遮罩先"落笔"(draw 秒内墨心凝聚),再沿纸纤维向外洇开(湿边 √t 扩散、水痕 tide line、纤维毛细、积墨、斑驳、颗粒);soft:1 保留遮罩灰度(远山淡墨) src at draw dur spread haloEnd color density halo rim fibre mottle grain pool warp wipe:{dir,dur} fade:[t0,t1] seed
inkWash(o) 水墨化后期:把彩色 SVG 变成湿墨(边缘积墨加深、柔和晕边、水痕、纸纹颗粒、12fps 抖动);源元素在 DOM 中被隐藏 src hide boil wobble dark edge bleed grain mottle tide alpha ink
particles(o) GL 点精灵粒子:drop / splat / mist / petal / spark / dot;落地的墨滴变成晕开的墨点并在"定型"后缓存 同 vk.particles + shape color color2 colors blend soak
mist(o) 飘动的雾带(山间留白) y height speed density scale color seed
shader(o) 自定义片元着色器(有 uTime uStep uProgress uRes、scenePx() paperN() fbm()) frag uniforms step key blend

粒子(纯数学,vk.particles):每个粒子的状态是 (seed, i, t) 的闭式解(线性阻力 + 重力的解析弹道、值噪声摆动、floor 侧视落地 / landAt 俯视落地),发射在固定槽位(burst:[{t, n, x, y}] 或 rate + from/to),发射器 point / line / box / radius。P.at(t) 返回 [{id, x, y, size, alpha, rot, landed, settled…}],与求值顺序无关。预设:inkDrops splatter spray petals sparks mist。

线条 boil / 手绘抖动(确定性、按 12fps "一拍二" 步进):

  • vk.gl.boil(sc, targets, {fps: 12, amp, freq, octaves, frames}):SVG 湍流位移滤镜,种子由场景时间步进计算。
  • vk.gl.jitter(d, t, {fps, amp, seed, frames, smooth}):路径点扰动(同一"张"内不变,下一张重画;A/H/V 命令保持不变),vk.gl.jitterPoints。

剪纸(上美厂风格预备):vk.gl.paperCut(v, {prefix: 'pc', rough, grain, shadow: [dx, dy, blur, opacity]}) 注入 #pc-cut(剪刀毛边)、#pc-grain(纸纤维明暗)、#pc-shadow(纸片投影)与 #pc(三者合一),用于 <g filter="url(#pc)"> 的平涂形状(配合 fill-rule="evenodd" 做窗花镂空)。

捕获与性能:

  • 所有 GL 效果共用每个视频一个离屏 WebGL1 上下文(preserveDrawingBuffer,预乘 alpha),每层把结果同步 drawImage 到自己的 2D canvas(willReadFrequently,CPU 后备),因此截图不会空白,也不依赖合成器时序。
  • 默认捕获(beginframe,chrome-headless-shell,--gpu soft = SwiftShader)与 vk qa / stills / contact(Playwright Chromium + SwiftShader)都有 WebGL,无需额外 Chrome 参数;--gpu off 会关闭 WebGL(层会打印一次警告并保持透明)。
  • 缓存:每个效果给出缓存键(paper 恒定、inkBleed 完成后恒定、粒子全部定型后恒定),键不变就跳过 GL。尽量用 rect 缩小区域、scale:.75 降低内部分辨率、遮罩用 static。vk.gl.stats() 查看 pass 数与耗时。
  • 示例:examples/gl-ink-demo.html(20 s:墨滴溅落 + 竖排题字洇开、远山分层晕染 + 雾带 + 渔舟 jitter + 水纹 boil、荷塘 SVG 水墨化 + 水花 + 落花、剪纸窗花),examples/tadpole/tadpole-gl.html(《小蝌蚪找妈妈》片头的 GL 版:片名湿笔书写、池塘活动层水墨化、落水滴与水花、宣纸纤维叠加;原文件未改动)。

风格库(vk.style,styles/<id>/)

Open style system (schema v2). Packs are runtime-loaded from styles/<id>/ via ES modules (styles/boot.mjs / CLI inject) — adding a pack does not require rebuilding dist/vidkit.js. Published schema: docs/style.schema.json (palette, fonts, motion grammar, look chain, materials, sound, qa[], lineage, renderCost). CLI: vk style new --from "…" / --ref img.png (scaffold + peek loop; honest: not magic), vk style mix a b --w .6, vk style fork <id>, vk style gallery (lineage + cost on cards). Recipes: recipes/*.html with vk-recipe front-matter.

一个风格包=一个目录,全部离线可用(字体随包,纹理/材质为程序生成的 SVG 滤镜或 vk.gl 着色器,音乐为代码合成):

styles/<id>/style.json    数据:调色板 palette(天空/远山/中景/地面/树…)与色相 hues(角色用色名 red/gold/blue…)、
                          材质 material(cut 剪纸 / ink 墨线 / flat 扁平 / leather 皮影 / decor 重彩描金 / neon 霓虹 /
                          pixel 像素 / crayon 蜡笔)、主题 theme(字体/字幕条)、video{texture, fadeOut}、转场
                          transitions{default, soft, strong}、排版 typography、声音 sound{voice, sfx 映射, music}、
                          节奏 pacing、镜头 camera{establish, dialog, action, push, punch}、角色约定 characters、
                          特效预设 effects、样片 demo、QA 清单 qa[]
styles/<id>/style.js      运行时钩子(vk => ({ decorate, post, title, label, effect, music, charAfter, … }))
styles/<id>/preview.html  ~5 s 样片(styles/demo.js:同一脚本 = 片名 + 走路入画的角色 + 招牌特效 + 转场)
id 名称 一句话
ink 水墨 宣纸、淡墨远山 + 浓墨勾线、雾带留白,竖排书法片名 + 朱印,vk.gl.inkBleed 题字洇开,古琴竹笛
papercut 剪纸(上美厂) 彩纸层叠、剪刀毛边与镂空、纸片投影,红色题匾,纸屑花瓣迸散,锣鼓点
shadow 皮影 油灯幕布(微颤)、半透明染色驴皮人物 + 镂刻花纹 + 操纵签子,雕花牌匾,梆子
opera 重彩装饰(大闹天宫) 石青石绿朱红金黄平涂、粗墨线、层叠祥云与天宫殿宇,金光放射,急急风锣鼓
tech 科技宣传 深蓝底、发光透视网格、电光蓝强调色、Archivo 粗体大标题,脉冲环,鼓点 + 合成器
neon 赛博霓虹 雨夜都市、霓虹线描人物、霓虹招牌点亮 + vk.gl.bloom 辉光、CRT 扫描线,琶音
pixel 像素 16 色(Sweetie-16)、整帧 4 px 像素化(确定性 SVG 滤镜)、打字机标题,金币迸出,芯片音乐
crayon 蜡笔绘本 画纸纹理、蜡质颗粒、线条每秒 8 次“沸腾”、站酷快乐体彩色标题,涂鸦星星,卡林巴
reel 动态海报 纸白 / 墨黑 + 粉黄青紫平涂、Archivo Black 超粗字 slam + 残影 + 硬投影、默认 stripes 彩条转场、冲击波环 + 放射线 + 白闪、128 BPM 合成鼓组(kick / hat / clap / whoosh / riser / 结尾和弦)
const v = vk.video({ style: 'papercut' });                    // 主题、质感、默认转场、缓推、混音参数、字幕风格
const v = vk.video({ style: ['ink', 'papercut.chars'] });     // 组合:水墨世界 + 剪纸角色(也可 'ink-bg' / 'papercut-chars')
const v = vk.video({ style: { base: 'neon', chars: 'pixel', sound: 'opera' } });   // 按角色拆分:world/chars/type/motion/sound/fx
const S = v.style;                                             // 或 vk.style('ink')
vk.scene('开场', 5, { transition: S.transition('default') }, sc => {
  const W = S.world(sc, 'mountain dusk pine moon');           // 场景词:地点/时间/道具(中英均可:山 黄昏 松 月亮)
  const hero = S.character(W.actors, { look: { hairStyle: 'bun', cloth: 'red' }, scale: .7 });   // 通用侧面角色,按风格材质绘制
  S.title(sc, '片名', { sub: 'subtitle' });  S.effect(sc, 'signature', { at: 1, x: 600, y: 300 });
  sc.on(l => hero.render(l, { x: 300, ground: W.ground, d: walked(l), clip: 'walk' }));   // d = 走过的距离 → 脚步锁定
  S.sfx(sc, 'step', .4);
});
S.music(v);                                                    // 风格配乐(确定性合成 bed)
  • vk.style.list() / .get(id) / .register(json, vk => runtime)(注册自己的风格包);现有 theme: 用法完全不变(风格包的主题注册为 style:<id>)。
  • vk.style.kit(svgLayer / overlay / burst / ease…)、vk.style.material(id)、vk.style.bed(v, {bpm, tracks}) 步进音序器、vk.style.transitions(tear 撕纸 / pixel 像素擦除 / cloud 祥云 / scribble 涂鸦 / lamp 灯灭 / scan 扫描;首次使用风格包时才注册进 vk.transitions,不用风格的页面转场表不变;单独使用可先调 vk.style.installTransitions())。
  • 画廊:vk style sample 渲染全部样片(MP4 + 海报 PNG),vk style gallery 生成 out/styles/index.html(卡片:海报、循环样片、简介、色板、用法片段)并截图 gallery.png。

故事 → 短片:vk make

vk make --style papercut --story examples/stories/kite.md -o examples/kite-papercut/   # 生成页面(故事内联为可编辑数据)
vk tts examples/kite-papercut/kite-papercut.html                                       # edge-tts 旁白/对白 + 词时间 + 口型包络
vk render examples/kite-papercut/kite-papercut.html -o out/kite-papercut.mp4           # 或 vk make … --tts --render

故事格式(markdown;也接受同结构的 JSON):

# 小芽的风筝
sub: 一个很短的故事
cast 小芽: girl                         ← 发型(bun/twinbuns/pony/long/short/cap/bald)、颜色名、girl/boy/elder…、音色 id
cast 阿公: elder cap blue gold grey

## 山顶 @ mountain day pine             ← 场景名 @ 场景词
- 阿公 enter right                      ← 动作:enter/exit/walk/run/wave/cheer/point/talk/bow/surprise/think/look/sad/jump/face
> 阿公和小芽,爬上了山顶。               ← 旁白
阿公: 风来了,松手吧!                   ← 对白(按角色分配音色,说话时口型同步)
- 小芽 cheer                            ← 动作挂在上一行台词开始时
- effect                                ← 风格招牌特效(+ 打击推近);也可 - shot close 小芽 · - sfx big · - hold 1.5

vk.film(story, {style}) 把它变成:每个故事场景一个 dur:'auto' 场景(时长由配音决定)、风格世界、角色站位(从左入场的占左侧位,不交叉)、脚步锁定的走路(停在双脚着地的位置)、手势淡入淡出、对白口型(vk.motion.mouth:有 TTS 包络时按响度/频谱质心选口型,否则按词时间)、镜头表(风格的 establish/dialog/action 景别;有人在别人台词时动作就用双人镜头)、片名、特效、脚步声与配乐。

vk style extract ref.png [--id x] [--k 6]:参考图 → 风格包起步文件(style.json + 空 style.js + palette.svg)。做法很简单:96 px 缩略图上的确定性 k-means 取 k 色(按占比排序,最亮→天空/纸,最暗→墨线,最饱和→强调色),384 px 图上的高通亮度均值估计颗粒(→ texture grain/rice 强度),边缘密度粗判材质。它只是起点,世界/标题/特效钩子仍需手写。

镜头与动作(Phase 3)

镜头(src/core/camera.js,纯函数):

sc.shots([
  { t: 0, shot: 'full', on: sub, follow: .35 },               // 景别 + 跟拍(平滑滞后 .35 s)
  { t: 2.1, shot: 'medium-close', on: sub, lookroom: .1 },     // 切近景(视线方向留白)
  { t: 2.8, shot: 'full', s: 1.45, on: sub, d: .3 },           // d:混合时长(视窗矩形插值,不漂移)
  { t: 3.7, punch: .16, at: [x, y], d: .55 },                  // 打击推近(快起慢回)
  { t: 5, pan: [x, y], d: 1.2 }, { t: 7, dolly: 1.3, at: [x, y] },
], { keep: [sub, sub2], margin: .05 });                        // 每帧把这些头部框保持在画内(必要时拉远)
// sub(t) → { head: [x, y], headR, feet: [x, y], facing }:通常由 rig.point 求出(puppet.subject(t, state) 现成)

景别:extreme-wide / wide / full / medium-wide / medium / medium-close / close / extreme-close(别名 ws/ms/mcu/cu/ecu)。vk.cam.frameShot / keepInFrame / clampView / punchEnv / smoothFollow / shotCamera 可单独使用;sc.toScreen([x, y], t) 把世界坐标换成屏幕坐标。相机关键帧默认行为不变(省略 x/y 回到 640/360);vk.video({cameraHold: true}) 或 sc.camera(keys, {hold: true}) 让省略的 x/y/s/r 沿用上一帧,避免“只写 s 就跳回中心”。镜头表 shots 不受此开关影响。

动作(vk.motion,src/fx/motion.js,纯函数):

  • gait({stride, duty, hip, leg, lift}) → .at(d):给定走过的距离 d,返回两只脚(着地时世界 x 恒定 = 不滑步)与髋高;根的速度由步幅推出;.rest(d) 给出双脚着地的停步距离。配合 IK 腿:rig.solveIK('legN', ankle, pose, root)。
  • mouth(seg, t) 口型(M/A/E/O 四个 viseme,12 fps 步进):优先用 vk tts 写入的响度/质心包络(env),否则用词时间。
  • boilPoints(points, t, {fps, amp}) 线条沸腾;follow / spring / drag 跟随与弹簧(确定性固定步长积分);ribbon(anchor, t, {n, len, lag}) 不可伸长的飘带(每段等长,滞后于锚点的历史位置)+ ribbonPath 描边。

示例:examples/wusong/wusong-v2-scene.html(与原片同一套 rig 与配音)。

动态图形套件(vk.mg)与运动模糊

从一支 15 s / 128 BPM / 8 个一小节场景的 Canvas 动态海报 reel 中提炼出的可复用能力(src/fx/mg/)。全部按需启用: stripes / bars 转场、slam 等文字特效与 dotwave 背景在页面第一次用到名字时才注册,不用它们的页面注册表(及 FX Gallery 的计数)与原来完全一致。 完整示例:examples/reel/reel.html → out/reel.mp4(与参考原片的对照:out/reel-original.mp4、out/reel-compare.png)。

子帧运动模糊(默认关):每个输出帧 = 快门窗口内 N 个子时刻的平均(窗口结束于帧时刻,t 在 0 处截断)。

vk.video({ motionBlur: { shutter: '1/40', samples: 4 } })   // shutter: '1/40' | '180deg' | '25ms' | 0.025 秒
vk render page.html                          # 页面开了 motionBlur 就用;
vk render page.html --shutter 1/60 --samples 6   # 命令行覆盖;--no-motion-blur / --shutter 0 关闭

vk render 在捕获管线里做:每帧按子时刻 seek N 次,ffmpeg tmix 等权平均后再编码(info.frameT 保持名义帧时刻,HUD 等不糊)。 canvas 图层也可单独在页内模糊:sc.canvas(draw, { motionBlur: true | 'video' | {shutter, samples} })(预览即可见;vk render 管线模糊时自动跳过,不会糊两次)。 vk stills / vk contact / vk qa 不做运动模糊。reel 示例 1080p 450 帧 8 核:无模糊 13.6 s,4 子帧 32.9 s。

画布绘制器((g, local, info) => …,用 sc.paint([p1, p2], {z, blend, motionBlur}) 叠在一个 canvas 层上,坐标为舞台像素):

名称 作用
vk.accents.rings({every:1, delay, speed, max, colors}) 每拍一圈扩散冲击波环(颜色轮换、随半径淡出);at/times 改为场景内指定时刻
`vk.accents.streaks({at, n, dir:'x' 'y', reverse})`
vk.accents.burst({every:.5, n, r0, spread, len}) 放射线,每拍 / 半拍重新触发
vk.accents.flash({every:1, amount, k}) 每拍白闪(指数衰减)
vk.accents.orbit({n, r, ry, speed, kick}) · plus({points, kick}) · disc({r, at, pulse, dx, dy}) 环绕圆点 · 旋转十字 · 弹出圆盘
vk.mg.morphSeq({at, shapes, palettes, echoes, cut, counter, flash}) 圆→方→三角→星,每拍一形(outBack)、描边回声、反向旋转内镂空、每拍换底色、轮廓数字、白闪
vk.mg.dotwave(o) / bg:{type:'dotwave', hole:{w,h}} 点阵波浪背景
vk.mg.converge({at, iris, star}) 形状螺旋汇聚(inExpo)→ 纸色圆形展开 → 旋转星标
vk.mg.hud(o) / vk.hud({title, meta, bars, duration}) 裁切角标、REC 闪点、时间码 MM:SS:FF、BAR n/8、进度条;全片 canvas,difference 混合

节拍类绘制器读取视频的 BeatGrid(bpm),与其它节拍工具一样提前一帧落拍;只取场景开始之后的拍。

节点(像其它元素一样 sc.add();尺寸为 720p 像素自动缩放,时间为场景内秒或 'b:N'):

名称 作用
vk.ui.ringCard({label, value, fillAt}) 进度环卡片 + 数字滚动
vk.ui.toggle({label, sub, click}) 开关,滑块移动时挤压变形、颜色过渡
vk.ui.equalizer({bars}) · vk.ui.like({click}) 均衡器 · 点赞(回弹 + 放射线)
vk.ui.chips([...], {colors}) 胶囊标签错峰滑入 + 轻微浮动
vk.ui.cursor({keys:[[t, x, y]…], clicks:[t…]}) 光标路径(inOutCubic),点击缩小 + 涟漪;x/y ≤ 1 为画面比例
vk.montage(words, {every:'b:0.5', palettes, counter, dots, flash}) 半拍一词的关键词快切:每词一套配色、砸入(交替方向)、奇数描边 / 偶数硬投影、放射线、0n / 08 计数、进度点、白闪
vk.lockup({title, sub, tagline, at, fadeOut}) 汇聚收束 logo:形状汇聚 + 纸色圆展开 + 星标 + mask-rise 标题 + 高亮条 + 色点 + 淡出到墨色

UI 组件可以直接放进 vk.device(vk.col([...]), {type:'phone'})。纯数学(vk.mg.subTimes / coverBars / shapeOutline / morphState / dotwaveAt / letterDrop / slam / echoGhosts / cursorAt / toggleKnob / likePop / montageSlot / timecode / convergeAt / recentBeats …)见 src/fx/mg/math.js,测试在 test/mg.test.mjs。

3D:vk.three(three.js r186,可选)

dist/vidkit-three.js(约 860 KB,可离线使用)是独立的可选包,里面打包了 three r186(vendor/three/,MIT)、所需 addons(GLTF/Draco/HDR/Font loaders、RoomEnvironment、RoundedBox/TextGeometry、BufferGeometryUtils/SkeletonUtils),以及 vidkit 的 3D 层和各模块。不加载这个文件的页面完全不受影响,核心 dist/vidkit.js 只多了一个 video.waitFor() 钩子。

<script src="../dist/vidkit.js"></script>
<script src="../dist/vidkit-three.js"></script>   <!-- 加载后才有 vk.three / sc.three / 风格包 three-tech -->

图层 API

sc.three(setup, update, opts)        // setup({THREE, scene, camera, renderer, rand, load, assets, layer}) → 可返回 Promise / update / {update, camera}
                                     // update(localT, info):必须是 t 的纯函数(每个子帧样本调用一次)
sc.three(module | [modules], opts)   // modules = vk.three.turntable(…) / vk.three.particles(…) / {setup, update}
v.three(...)                         // 全片层(默认 z:'front');场景层默认 z:'back'(在文字后面)

opts 包括:res(内部分辨率比例,默认 0.75,输出仍按 dpr 全分辨率)、aa(抖动子帧数,兼作抗锯齿)、motionBlur({shutter, samples},默认继承 vk.video({motionBlur}))、camera(rig 函数或 {pos, target, fov, roll})、fov、background(不设则透明,按预乘 alpha 叠进图层栈,辉光也会透出)、assets {name: url}、seed、z/zIndex/rect,以及 post:

post 键 默认 说明
exposure · tone 1 · 'aces' HDR 曝光 + ACES(three 的拟合版)
bloom {strength, threshold, knee, radius, clamp} .55 · 1 · .6 · 1 · 40 便宜的下采样/上采样泛光(13-tap Karis 预滤 + tent 上采样)。所有子帧先在 HDR 里累加,再做一次泛光
grade 'neutral' 预设 teal-orange cool warm bleach mono cyber,或 {temperature, tint, lift, gamma, gain, contrast, saturation, shadows, highlights, split}
vignette · grain · ca .18 · .02 · 0 暗角、胶片颗粒(带 dither)、色差
dof {focus, aperture, maxBlur} 关 深度采样景深;turntable 会自动对焦到产品
fade · fadeColor 0 渐隐到某个颜色(1 = 全黑)

所有 post 值都可以写成 t => …。

预加载与确定性:load.gltf/hdr/env/texture/image/font/json 都会进 video.waitFor(),所以 window.__ready(也就是开始捕获)会等它们全部完成,接着编译 shader 并预热一帧。整条路径不读真实时钟:AnimationMixer 用 vk.three.mixer(root, clips).at(t) 按时间设置,vk.three.frameIdx(t, fps) 给出帧号,随机数只用种子 rand。所有 3D 状态都是 t 的纯函数,所以多个 worker 并行渲染得到的帧逐像素相同。vk qa 现在会再开一个全新页面(模拟另一个 worker),在若干时间点比较 three 层的像素哈希,输出 [three] … identical across 2 workers;不一致就算 ISSUE。

运动模糊:three 层在层内做子帧累加,子帧时间来自 motionBlurCfg,再叠加 Halton 抖动作 AA,累加在泛光之前完成。vk render --shutter … --samples … 走管线模糊时,three 层按名义帧时间渲染一次,然后在 N 次管线子 seek 中保持像素不变,因此不会被模糊两次,3D 也只算一遍。--shutter 0 会同时关掉层内模糊。

模块

模块 说明
vk.three.turntable({product | model, spin, angle, tilt, float, lid, sweeps, sweep:{every,…}, env, backdrop, floor, shadow, material, animate}) 产品转台。环境有 'studio'(程序化影棚:顶灯箱 + 竖灯条 + 轮廓条 + 前灯箱 + 低位反光板,PMREM)、'room'(RoomEnvironment)、'loft'(随包的 Poly Haven CC0 HDRI,1k)或任意 .hdr。另有无缝弧形背景、带径向淡出的光面地板 + 镜像反射、模糊接触阴影、灯条扫光(有限距离的竖直灯条在材质 shader 里解析计算反射,带视差,平面上也会滑过)、DOF 自动对焦。product 可选 'earbuds' 'earbud' 'phone' 'bottle'(程序化),也可以用 model:'x.glb'(自动缩放到 height,带动画就自动挂上 mixer)
vk.three.particles({n, targets, morph, beat, intensity, size, drift, twinkle, flare, position, scale}) 5–20 万粒子,变形全部在顶点 shader 里完成。target 可以是 galaxy sphere torus cloud、{text, font}、{draw(g,w,h)}(2D canvas 画的 logo)、{asset | image}(图片)。morph:[{t, to, d, style:'converge'|'burst'|'swirl'|'direct'}] 带逐粒子错峰;beat:{amp,k,every} 跟随 vk.video({bpm}) 的节拍网格(也可以传函数);采用加色混合,intensity 按密度调整
vk.three.materials.* chrome metal gold titanium anodized glass(transmission)glassLite ceramic plastic matte rubber screen
vk.three.product(name, o) · vk.three.studioScene(o) · vk.three.sweep() 单独取用产品、影棚场景、扫光注入

镜头 rig(vk.three.rig,纯函数 t → {pos, target, fov, roll})

orbit · dolly · push · fly({points, look, bank})(向心 CatmullRom,按弧长匀速)· crane · zoomScale(对数距离,"powers of ten")· keys([{t, pos, target, fov, ease}]) · seq([{t, rig, blend}]) · shake({at, amp, rot, freq}) · punch(与 vk.cam 用同一个 punch 包络)· add(base, ...mods);另有 vk.three.path(points) / kf / rig.lerp。纯数学函数(rig、路径、采样计划、ACES/调色、粒子目标、mask 采样)的测试在 test/three.test.mjs。

风格包 three-tech(3D 科技)

styles/three-tech/ 由 dist/vidkit-three.js 注册,核心包里没有它。它提供近黑影棚、电光青 + 紫两种强调色、cyber 调色、扫描线片名、粒子 + 光环特效、96 bpm 合成器脉冲铺底,以及 v.style.base.stage3d.{layer, turntable, particles} 预设。样片 out/styles/three-tech.mp4,已收进画廊。style.json 新增两个可选字段:requires(需要额外加载的脚本,画廊卡片会显示)和 poster(vk style sample 截取海报帧的时间)。

3D 基元:look / diorama / shaderPlate / text3d / sim / terrain · globe / model(Phase B)

这些基元按"可组合"设计:任何 3D 层都能接一条 NPR look 链,所以水墨、剪纸、像素、霓虹之类的画风不需要专门的 3D 风格代码,换一个 look 就行。所有模块都满足"每帧是 t 的纯函数",可以 seek,也能多 worker 并行渲染。

API 作用
post: { look } / 层参数 look 合成之后在显示空间里串一条 NPR 链。预设:ink watercolor papercut pixel neon comic blueprint sketch miniature;pass:toon(亮度分档、保留色相)posterize palette ink outline(深度 + 由深度重建的法线,或 normals:true 真法线 pass;wobble/boil 手绘抖动)edges kuwahara(水彩/油画平涂)paper(纤维、边缘晕染)halftone pixel glow tiltshift mist(深度雾)hatch。写法:'ink'、[{type:'toon'},{type:'outline',width:2}],或 {preset:'ink', mist:{density:.7}, paper:false};参数都可以写成 t => 值
vk.three.diorama({kind}) papercut(分层剪纸灯箱:N 层剪影 + 层间软阴影 + 背光 + 画框,层可以 rise/sway/slide)· popup(立体书:沿书脊开合,纸片绕底边铰链立起;spreads + turns 翻页,翻页纸正反面印着前后两页;printLeft/printRight 用 canvas 印字;lift 让太阳/云立在纸条上)· isometric(低多边形小岛 + 底座 + 正交相机,diorama.isoRig)· tiltshift(微缩,自动接 miniature look)。剪影来自纯函数 vk.three.shapes(ridge hills mountains waves forest city pine tree house pagoda cloud circle crescent star bird boat grass rect,以及 SVG path)
vk.three.shaderPlate({preset | sdf | glsl}) 全屏 raymarch / SDF / GLSL 画面,写进 HDR 场景缓冲,因此 AA 抖动、运动模糊子帧、泛光、调色、look 都会生效。相机射线来自 rig。预设 metaballs tunnel nebula rings;自写 float map(vec3 p) + 可选 shade / bg,库函数见 vk.three.glsl;depth:true 写入深度,网格可以和它穿插
vk.three.text3d({text, font, in, out, wave}) 挤出 + 倒角的 3D 字,逐字入场/出场(rise drop flip scale spin swing type pop,带 stagger/order)。自带字体 archivo-black anton instrument-serif(由 OFL 字体转换为 typeface JSON);中文请用 vk font3d 字体.ttf --chars "只用到的字" 生成子集
vk.three.sim({init, step, dt, every, duration}) 固定步长模拟。每 every 秒存一份精确快照,at(t) 从最近的快照往前推,结果与从 0 跑一遍逐位相同。快照经 vk 磁盘缓存在 worker 之间共享,所以有状态的物理也能 seek、能并行。用法:S.module({setup, render(state, t)}),或 await S.ready(ctx) + S.at(t)
vk.three.terrain({type, colors, scatter, water, block, contours}) 高度场地形:fbm hills mountains ridged island mesa dunes、函数 (x,z)=>0..1 或灰度图。支持色带(alpine island desert ink paper lava mono)、坡度岩石、雪线、地层侧壁、水面、等高线,以及实例化散布 pine/tree/rock/house(可 grow 逐个长出)。heightAt(x,z) 可以用来给相机贴地
vk.three.globe({texture, markers, arcs}) 地球:随包 Natural Earth 1:110m 陆地(公有领域,离线栅格化)或程序化纹理,经纬网、大气边缘光;标记点会弹出,大圆弧线随 drawRange 画出
vk.three.model(url, {size, timeline, ground, spin}) GLB/glTF 模块:Draco/meshopt 都能读,自动缩放并落地,timeline 让动画片段按 t 交叉淡化,缺灯时自动补光
vk.three.mixer(root, clips, {timeline | weights}) at(t) 按时间线混合片段(纯函数 mixerTimeline);不传 timeline 时行为与旧版相同

命令行

vk asset add model.glb --licence CC0-1.0 --author "…" [--draco] [--name id] [--dir examples/assets/models]
             # glTF-Transform: dedup/prune/resample/weld + meshopt(默认)或 Draco → <name>.glb
             # 写 assets.lock.json(来源、许可、作者、源文件与产物的 sha256 + 字节数、片段名)+ 转台缩略图 <name>.thumb.png
vk asset list | verify       # verify 重新计算哈希,有漂移则 exit 1
vk font3d font.ttf --chars "千里江山" -o fonts/typeface/x.json   # 字体 → three typeface JSON(OFL 衍生物仍为 OFL)
vk adopt demo.html -o out.mp4 --duration 10 [--fps 30] [--timers] [--canvas]

vk adopt 用于录制现成的实时 demo(基于 requestAnimationFrame 和 performance.now 的 three.js / canvas / CSS 动画),不用按 render(t) 改写。它在页面脚本之前注入时间垫片:冻结 performance.now / Date,接管 rAF,给 Math.random 设种子,--timers 时 setTimeout/setInterval 也走虚拟时钟,WAAPI/CSS 动画和 <video> 会对齐到虚拟时间。之后每帧把时钟推进 1000/fps ms 再截一帧。只能顺序录制:实时 demo 的状态是之前每一帧的累积,无法 seek,也无法拆给多个 worker 并行,所以比 vk render 慢。需要并行、可 seek 的话,把页面改写成 vk.video,或者把有状态的部分放进 vk.three.sim。

可选依赖(optionalDependencies,缺失时只影响对应命令):@gltf-transform/*、meshoptimizer、draco3dgltf(vk asset),opentype.js(vk font3d)。

示例

  • examples/ink-landscape/ink-landscape.html(15.5 s)·《千里江山》:程序化群山 + 900 棵逐渐长出的松树(低空飞越)→ 自定义高度函数做出的江谷,纸片小舟漂流、飞鸟掠过 → 3D 书法字(马善政子集)从雾中升起。全片只用 terrain + text3d + look:'ink'。→ out/ink-landscape.mp4 · out/ink-landscape-sheet.png
  • examples/popup-book/popup-book.html(19 s)·《纸上山海》:立体书打开,山村纸片依次立起(云、太阳立在纸条上)→ 翻页,光线由昼转夜,夜海和小舟立起 → 尾声换成分层剪纸灯箱。用到 diorama popup + papercut 和 look:'papercut'。→ out/popup-book.mp4 · out/popup-book-sheet.png
  • examples/three-character.html(10.6 s):RobotExpressive(CC0,vk asset add 压到 216 KB)按 Idle → Walk → Wave → Dance 的 mixer 时间线播放,第二段是同一个模型套 look:'comic'。
  • 测试:test/three-b.test.mjs,每个模块至少一个测试(look 展开、shapes、地形数学、plate 源码、逐字进度、sim 逐位一致、mixer 时间线、diorama、adopt 时间垫片、资产锁、font3d),另有一个浏览器冒烟测试:所有模块放在同一页,strict 模式 + 确定性复查。

渲染耗时(8 核,SwiftShader,无 GPU,8 个 worker,1280×720,res .75,无运动模糊):

片子 帧数 帧阶段 总耗时
ink-landscape 465 478.7 s(1.0 fps;Kuwahara + 带抖动的描边 + 900 棵实例松树最贵) 8 分 05 秒
popup-book 570 169.2 s(3.4 fps) 2 分 53 秒

迭代时用 vk peek --draft:水墨片 11 帧约 11 s,立体书 8 帧约 7 s。

示例与性能

  • examples/three-basics.html(11 s):粒子星系变文字、耳机转台 + 扫光、手机 orbit + DOF。
  • examples/three-promo/three-promo.html(24 s,1080p):虚构耳机 "LUMEN Buds" 的宣传片。依次是粒子 logo 组装(zoomScale 推进 + 节拍脉冲 + burst + shake)、bars 覆盖转场、转台主镜头(开盖 + 两道扫光 + DOF)、CatmullRom 穿梭 + 浮尘、三色并排、crane 片尾。另有 three-tech 铺底 + edge-tts 中文旁白(vk tts 生成 three-promo.vo.json)+ 逐字字幕,运动模糊开启。
    vk render examples/three-promo/three-promo.html -o out/three-promo.mp4 --scale 1.5
    

渲染耗时(8 核,SwiftShader 无 GPU,beginframe,8 个 worker,层内运动模糊 4 个子帧,res .75):

片子 帧数 · 分辨率 帧阶段 每个 worker 每帧 render(t) + 捕获 总耗时
three-promo(--scale 1.5) 723 · 1920×1080 497 s(1.5 fps,墙钟 ≈ 0.69 s/帧) 3.6 s + 0.77 s 8 分 30 秒(含音频混音)
three-basics 330 · 1280×720 109 s(3.0 fps) 1.66 s + 0.17 s 1 分 56 秒
three-tech 样片 165 · 1280×720 — — 64 s

冷启动:每个 worker 启动时要做 PMREM 预滤波、粒子目标采样和 shader 编译。现在 PMREM 环境与粒子目标按内容哈希(three 版本、GL 渲染器、参数、生成函数源码、栅格化像素)缓存到磁盘(~/.cache/vidkit,VK_CACHE_DIR 可改;?cache3d=0 关闭),同一次渲染的 8 个 worker 与之后的渲染共用;__ready 前只在 64 px 的内部尺寸上预热一帧(编译程序、上传缓冲),不再在 t=0 全尺寸画一遍。three-promo 实测(8 核,8 个 worker 同时打开到第一帧,平均每个 worker):旧 57.5 s → 无缓存 16.3 s → 有缓存 9.3 s → --draft 8.0 s;单 worker 12.0 s → 3.0 s(+首帧 1.0 s)。缓存命中与未命中的帧与旧版逐像素相同。

草稿:vk peek --draft / vk render --draft(或 vk.video({draft:true}))让 3D 层用 res ≤ .35、aa 1、关闭层内运动模糊、景深与泛光(2D 页面 render 默认 --scale .5、CRF 26、preset veryfast)。想再加速可以调低 res 或 motionBlur.samples,或者用 aa: 1。

限制

  • 只支持 WebGL2(SwiftShader 软渲染),不支持 WebGPU。
  • DOF 是单遍深度采样的近似,前景边缘可能有轻微光晕;扫光是解析灯条,不是真实的环境贴图更新。
  • 接触阴影每个输出帧渲染一次(取第一个子帧),不是每个子帧都渲染。
  • 没有随包提供 TextGeometry 用的 typeface 字体,文字建议用粒子文字或 DOM 叠加。
  • 地板反射是镜像克隆,不处理遮挡和粗糙度模糊。

面向 agent:严格模式、注册表、lint、peek、草稿

目标:让 agent(和人)写页面时更快发现错误,但不限制创作——预设、风格、模块只是起点,原生 DOM / CSS / SVG / Canvas / WebGL / three.js 代码始终是一等公民。agent 的入口文档:llms.txt(模型、黄金规则、最小示例、名称索引)与 AGENTS.md(工作流、手艺要点、坑)。

严格模式(vk.video({ strict: true });vk peek / vk qa / vk render 默认开启,--no-strict 关闭;页面 API 默认仍只警告,旧页面行为不变):

  • 未知的 fx / 转场 / 缓动 / 质感 / 背景 / 主题 / 风格 / 音效 / 3D 材质 / 产品 / 环境 / 调色 / 粒子目标名直接抛错,信息里带 did-you-mean(注册表上的 Levenshtein)、可用名称列表,以及写下这个元素的页面 文件:行号;
  • 渲染一帧期间调用 Math.random() 抛错(非严格模式只警告一次;setup 阶段的种子随机序列不变)。

注册表元数据:每个条目都有 {description, params:{名: {type, default, range, description}}, example}(src/meta/schemas.js;插件见编写插件)。

vk.list()                              // 种类:elements fx transitions textures backgrounds blocks eases themes formats sounds materials styles three threeMaterials threeRigs
vk.list('fx')                          // 名称(与旧版相同)
vk.list('fx', { detail: true })        // [{name, description, params, example, aliases, …}]

命令行 vk list / vk list fx / vk list three layer / vk list options(vk.video / vk.scene / 元素公共选项)。npm run docs 由同一份注册表生成 llms.txt、docs/api.json、docs/vk.d.ts,并提交进仓库;npm test 会检查它们是否最新。

vk lint page.html(acorn AST,vendor/acorn):找出渲染时会执行的闭包(sc.on / v.onRender / sc.canvas / sc.paint / api.fn / three 的 update、{update|draw|render|…} 成员、第一个参数叫 t/local 的函数,以及它们在同文件里调用的函数),标出 Math.random、Date.now / new Date()、performance.now、requestAnimationFrame、setTimeout / setInterval、THREE.Clock / getDelta、mixer.update、在闭包里调用的种子生成器、跨帧累加的外部变量,以及字面量里的未知名称——每条带行号和修复提示(vk.rand(seed) 在 setup 里预计算、vk.hash(i)、t、vk.three.mixer(...).at(t))。页面里 vk.use / vk.register 注册的名字会先收集,不算未知。行尾或上一行写 // vk-lint-ignore 可忽略。现有示例:除 nezha-ref/nezha-rig-demo.html(不是 vidkit 页面,3 条顶层定时器/时钟警告)外均为 0 error / 0 warning。

vk peek page.html:一次浏览器启动完成 agent 的"看片"循环:静态 lint → 打开页面(严格模式)→ 在 t=0(封面)与每个场景的入场中/落定两个时刻截低清静帧(或 --at / --every)→ 页内版面 QA → 像素分析 → 第二个全新页面在若干时刻重渲染做确定性比对 → 带标注的联系表。输出目录(默认 out/peek/<name>/)里有 still-*.jpg、sheet.png、peek.json: { ok, issues: [{severity, code, message, t, times?, hint, el?}], stills: [{t, file, scene}], sheet, timings, duration, scenes, warnings, lint, determinism }。 检查项(code):page-error(含严格模式错误)、unknown-name、lint/*、text-overlap、text-overflow-x/y、text-cut-by-frame、outside-safe-area、out-of-frame、in-platform-ui-zone、caption-*、fonts-not-loaded、blank-frame / blank-first-frame / dark-frame、low-contrast(在渲染出的像素上测文字与背景对比度)、flicker(t−1/fps · t · t+1/fps 三帧中间一帧突变)、nondeterministic(同一 t 在全新页面上渲染结果不同;无损 PNG 比对,容忍几级栅格噪声,并保存 fresh-t*.png 供对照)。落定帧上的版面问题是 error,入场动画中是 warn;有 error 时退出码 1。实测(8 核、无 GPU):promo 51.8 s / 27 帧 6.9 s,vertical 14.7 s(1080×1920)6.2 s,reel 15 s(1080p)8.2 s;examples/agent-test(10 s,含 3D)--draft 2.5 s。

草稿模式:vk peek --draft / vk render --draft(见 3D 示例与性能)。

示例:examples/agent-test/agent-test.html——只按 llms.txt + AGENTS.md 写成的 10 s 自测片:tech 风格 + 原生 canvas 星空(无状态)+ 一个小的 vk.three 环面结,经 lint → peek 循环后渲染为 out/agent-test.mp4(联系表 out/agent-test-sheet.png)。

字体许可

全部随包字体均为 SIL Open Font License 1.1(允许随软件打包、嵌入、再分发;不可单独售卖;修改版不得使用保留字体名;用这些字体渲染出的视频不受限制)。详见 fonts/LICENSES.md 与 fonts/OFL-1.1.txt。

字体 用途
Noto Sans SC(可变 100–900) 中文 + 拉丁,所有主题正文/标题
JetBrains Mono(可变) 代码、终端、数字
Archivo(可变 wght + wdth) 展示字体(bold / noir);stretch 特效动画字宽轴
Anton 窄体海报字(font:'condensed')
Instrument Serif(Regular / Italic) editorial 主题标题、引用
Ma Shan Zheng 马善政毛笔楷书 ink 主题书法标题
Noto Serif SC 思源宋体(可变 200–900) ink 主题正文、字幕
ZCOOL KuaiLe 站酷快乐体 crayon 风格包手写标题
Archivo Black reel 风格包 / vk.mg 海报大字、快切、logo 收束

示例数据来源:examples/data/co2.json 摘自 Our World in Data《CO₂ and Greenhouse Gas Emissions》(github.com/owid/co2-data,基于 Global Carbon Project,CC BY 4.0,2026-09-29 获取)。examples/assets/sample-screenshot.svg 为合成占位图(画面标注"示例截图")。

音乐素材(examples/assets/music/,详见 examples/mv/LICENSE-music.md):Kevin MacLeod(incompetech.com)《Voxel Revolution》《Wallpaper》节选,CC BY 4.0——使用或再发布成片时必须署名(示例片尾已署名)。MV 中的"人声"为 edge-tts 合成(微软在线服务,条款见 LICENSE-music.md)。

第三方代码与素材(vendor/,详见 vendor/LICENSES.md):three.js r186 及其 examples/jsm addons(MIT,© 2010-2026 three.js authors);Google Draco 解码器(Apache-2.0);Poly Haven《Photo Studio Loft Hall》HDRI(CC0,已降采样到 1k)。这些都只打包进可选的 dist/vidkit-three.js。

About

用 HTML 代码生成视频的确定性渲染框架:场景脚本、丰富效果库、一条命令导出 MP4

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages