Velxio 宣传视频制作管道
分为三个阶段,全部在此仓库中(velxio_docs; 开发机上位于 /home/dave/velxio_docs):
- 录制 —
scripts/promo-record.mjs驱动 staging 环境上的真实产品,执行端到端操作(空白项目 -> 选择 ESP32 -> 添加 220R 电阻 + LED -> 旋转电阻器 -> 通过引脚点击连线 -> 编写草图 -> 运行 -> LED 闪烁),并注入可见光标和点击涟漪。每个关键步骤都会记录{t, x, y, label}到scripts/promo-events.json;原始视频保存到scripts/promo-raw.webm。 - 节拍网格 —
scripts/detect-beats.py(librosa)将音轨转换为promo/src/beats.json(包含 BPM、节拍、军鼓、低音鼓)。 - 后期制作 —
promo/是一个 Remotion 项目。prepare.mjs复制录制内容,裁剪启动前的模态框,拼接掉编译等待时间,并输出src/data.json。src/Promo.tsx负责渲染相机(每个节拍中心放大,每次强拍都精确对齐到 0.34 秒内的最近音乐节拍)、字幕标签、一个纯色开场卡片、velxio.dev 结束卡片以及带淡入淡出的音乐轨道。
命令
cd /home/dave/velxio_docs
VELXIO_SHOTS_EMAIL='[email protected]' VELXIO_SHOTS_PASSWORD='<请查看 memory vstaging-test-user>' \
node scripts/promo-record.mjs # 录制(约 2-4 分钟,包含编译时间)
python3 scripts/detect-beats.py promo/public/soundtrack.mp3 --fps 30 \
--out promo/src/beats.json # 仅在音轨变更时运行
cd promo && node prepare.mjs
CHROME=$(ls -d $HOME/.cache/ms-playwright/chromium-*/chrome-linux*/chrome | sort | tail -1)
npx remotion render src/index.ts promo out/velxio-demo.mp4 --codec h264 --browser-executable "$CHROME"
推送到 GitHub 的可查看副本:media/velxio-demo.mp4(已提交;覆盖并推送可更新同一 URL)。promo/out/ 已加入 gitignore。
审查流程(不可跳过)
从 promo/src/data.json(ct 字段)中在节拍时刻提取帧,而不是猜测的时间 —— 不同录制之间的节拍会移动:
ffmpeg -y -ss <ct> -i out/velxio-demo.mp4 -vframes 1 /tmp/beat.png
检查:开场字幕可读,每次放大都能完整显示主体,字幕与屏幕内容匹配,光标未遮挡重要部分,最终 LED 点亮。
画廊演示视频(基础模式)
每个画廊示例对应一个短视频 —— 打开、运行、录制其工作过程 —— 包含一个分割式开场卡片(左侧为 Logo + 标题 + 开发板,右侧为完整电路)、一个底部三分之一区域、结束卡片和音轨。
node scripts/gallery-scan.mjs # 刷新 406 示例索引
node scripts/gallery-record.mjs [slug ...] # 1080p 录制(跳过已完成的部分)
node scripts/gallery-bbox.mjs [slug ...] # 测量电路的位置
node scripts/gallery-render.mjs [slug ...] # 每个录制生成一个 mp4
- 精选的演示集定义在
gallery-record.mjs顶部的GALLERY变量中;slug 来自scripts/gallery-index.json(缩略图文件名即为 slug)。 - 静态图像使用
deviceScaleFactor: 2捕获,并裁剪到电路边界框:清晰度足以填满半个 1080p 帧。不要放大应用以放大较小的电路 —— 画布以中心为锚点缩放,会导致电路移出屏幕;应重置视图。 - 边界框检测需要为每个示例创建一个全新的上下文:第二次在客户端加载编辑器会导致画布为空,无法测量任何内容。
- 无板的示例(数字/模拟类别)永远不会编译:“运行”按钮保持禁用状态,SPICE 引擎从一开始就驱动它们。
- 后端 QEMU 开发板(STM32、Raspberry Pi)不会输出“浏览器内”控制台行。此外,STM32 根本无法在 staging 环境上运行(libqemu-arm 是可选的资源,未部署在那里)—— 编译需要 3 秒,但永远不会启动。
- 原始录制内容(
promo/public/gallery/*.webm,每个约 3 MB)已加入 gitignore;电路静态图像和每个录制对应的 JSON 已提交,因此重新渲染只需要再次提供原始录制文件。
音乐
promo/public/soundtrack.mp3 = Mixkit "House Vibez" by Lily J(assets.mixkit.co/music/745/745.mp3),Mixkit Stock Music Free License —— 可免费用于商业用途,无需署名。123 BPM。替换文件并重新运行 detect-beats.py 可更改音轨;请保持 promo/public/ATTRIBUTION.md 中的许可说明为最新状态。
音轨以约 8 秒的前奏开始:Promo.tsx 中的 AUDIO_START 是检测到的第一个节拍,因此音频从该点开始播放,合成时间 t=0 落在重拍上。音量保持在 0.55,并在结束卡片上带有 0.9 秒的淡入和 2.2 秒的淡出。
风格规则(来自 David 的审查 —— 请遵守)
- 视频直接从编辑器开始,板模板模态框已打开,AI 聊天已最小化。没有主页,没有加载过程,没有可见的最小化点击(录制器在启动前以编程方式执行最小化;prepare.mjs 会裁剪到
start标记)。 - 开场标题放在一个纯色深色卡片上 —— 切勿在 UI 上半透明显示。
- 放大必须居中其主体:使用平移+缩放并带有边缘限制(
Promo.tsx),切勿使用 transformOrigin-at-point(这会使主体位于边缘并被截断,例如 ESP32 卡片)。 - 添加零件的节拍使用短暂停留(约 0.5 秒),以便缩放及时释放,从而看到零件的放置位置。
- 代码节拍使整个编辑器面板居中(fx/fy 覆盖 357,280)—— 在编写代码时切勿显示裁剪后的编辑器。
- 点击“运行”后,将光标移开(录制器移动到 700,620),以便按钮旋转器可见;“运行”节拍以中等缩放比例(1.8)放大编译/运行集群。
- 放置后,将电阻器旋转为水平方向(垂直方向默认会导致其自身导线在摄像头下重叠)。
- 指针是 macOS 风格的箭头,而不是圆点。热区数学(源自 saas-product-demo 技能):在 24x24 的 viewBox 中,尖端位于 (4,3),因此在渲染宽度 W 时,元素偏移量为 (-4W/24, -3W/24) —— 如果没有此偏移,每次点击都会偏差约 6-8 像素。
- 缩放强拍应落在音乐节拍上(请参阅上面的音乐部分);切勿为了让强拍对齐节拍而使其偏离其对应的点击超过约 0.3 秒。
- 在点击时模态框会关闭的节拍(如选择空白、添加零件)需要设置
lead: 0.45:峰值必须在点击之前到达,以便画面显示卡片仍处于打开状态,然后释放动画揭示零件的放置位置。如果在点击时达到峰值,则缩放会停留在一个已经关闭的对话框上。
陷阱(每个都曾导致一次失败的录制 —— 所有问题现在均已由脚本处理)
/即使在登录后也是营销着陆页;编辑器位于/editor。首先通过 fetch 在页面内进行 POST/api/auth/login来完成登录。- 在全新的
/editor上,“开始新项目”覆盖层会自动打开(.new-project-overlay),并拦截所有外部指针点击。首先与之交互,或以编程方式派发点击事件。 - 选择器的搜索输入框保留之前的查询条件 —— 在输入新内容之前,使用 Ctrl+A + 退格键清除,否则你会搜索出“esp32led”。
- 选择器卡片:通过
.component-picker-modal .card-name匹配精确标题(通用的文本引擎可能会命中模态框后面的 Monaco 令牌)。结果会进行防抖处理 —— 最多轮询 5 秒。卡片名称是精确的(例如“Resistor 220 Ω”使用 U+2126 风格字符,而非“Resistor”;请检查/components-metadata.json)。 - 开发板不要通过拖拽其主体移动 —— 将开发板保持在选择器放置它的位置(靠近画布右边缘),并相对于其实时边界框将小组件放置在开发板左侧,那里有空间。
- 引脚点击:使用应用自身的
[data-pin-overlay="true"][title=<pin>]div 元素,并选择最接近宿主元素的候选者(标题可能冲突:开发板引脚“2” vs 电阻器引脚“2”)。根据pinInfo偏移计算位置在旋转的零件上会失败。ESP32 引脚命名为 '2'、'4'、'GND'(而非 D2)。 - 通过计算
path[stroke="#1a1a1a"](每条导线的轮廓路径;导线没有类或 data 属性)来验证每条导线是否已连接。如果失败,则通过按 Escape 键并重新点击来重试一次。 - 电路验证器会阻止没有串联电阻的 LED 运行(会报 3.9e12 A 错误)。演示必须连接 GPIO2 -> 220R -> LED 阳极,GND -> LED 阴极。切勿发布需要点击“仍然运行”的录制内容。
- 空白模板附带一个默认草图 —— 在输入屏幕上的注释之前,先按 Ctrl+A,然后通过
monaco.editor.getModels()[0].setValue(...)设置完整的草图(逐字打字会与 Monaco 的自动闭合括号功能冲突)。 - “喜欢 Velxio?/ 在 GitHub 上为我们加星”的 Toast 通知会在录制时间超过约 5 分钟时干扰画面 —— 注入的清理脚本每秒会将其移除一次。
- Playwright 不录制操作系统光标:注入的
#vx-cursordiv 以及鼠标按下涟漪(context.addInitScript)是可见的指针。 - 编译等待是真实存在的(热启动 30 秒 - 冷启动 5 分钟):录制器记录
run和sim-started;prepare.mjs 会拼接掉这段间隔。模拟开始通过“浏览器内”控制台行检测到;“guest crashed”表示应中止。 - Remotion 通过
--browser-executable参数使用 Playwright 自带的 Chromium 进行渲染(此机器上没有下载额外的捆绑浏览器)。
参考仓库(2026-08-15 审查)
两个用于相同类型的 Claude-Code 技能,但采用不同的方法:它们从截图/原理图 UI 合成影片,并使用合成光标 —— 我们的方法录制真实产品。在技能升级时可以克隆它们:
github.com/noamdorr/saas-product-demo-video—— 在 Remotion 中制作 20-45 秒节拍同步的营销影片。值得借鉴:音轨节拍同步(librosadetect-beats.py:场景切换在军鼓上,场景内事件在低音鼓上 —— 我们的视频是无声的,添加音乐并对齐缩放节拍是当前可用的最大单一升级点)、光标热区数学(SVG 箭头尖端在 24 像素盒子中的 (4,3) —— 如果我们将点状光标替换为箭头,这将至关重要)、打字预算检查、迭代操作手册。github.com/Vincentwei1021/video-shotcraft—— 包含演示源和图库的 152 个镜头配方卡片(vincentwei1021.github.io/video-shotcraft)、一个经过批准的模板(Ink Press)、2.5D 相机移动、声音设计以及三种操作模式(模板/自主/共创)。值得借鉴:导演的镜头词汇及其最终审查清单;如果将来需要完整的电影风格影片,它也可以作为插件安装。
相关
- 截图管道:
scripts/shots.mjs(同一仓库)—— 除非 AI 面板是主体,否则会将其最小化。 - GIF:录制一段内容(Playwright recordVideo)并使用 ffmpeg 双通调色板转换;请参阅
scripts/weather-media.mjs获取缩放+裁剪模式(从元素的 boundingBox 获取裁剪区域)。 - Staging 测试用户:请查看
vstaging-test-user的内存(s3-tester, pro)。 - 损坏的展示项目(气象站)在 velxio-prod 仓库的
project/docs-portal-2026-08/STATUS.md中跟踪。