Communitygithub.com

velxio/velxio_docs

通过 Playwright 驱动真实应用并结合 Remotion 后期制作,生成或更新 Velxio 宣传/演示视频(及产品 GIF)。包含可见光标、关键点击放大、字幕、开场/结束卡片。

velxio_docs 是什么?

这是一个用于自动化生成 Velxio 产品演示视频的 AI 技能,它通过 Playwright 驱动真实的产品 UI,录制操作流程,然后使用 Remotion 进行后期制作,最终输出节奏同步的营销视频。该技能支持 Velxio 平台,适用于生成演示视频、产品动画、流程 GIF 等场景。其工作原理分为三个阶段:录制阶段,通过 `promo-record.mjs` 脚本端到端地操作真实产品,并注入可见光标和点击涟漪,记录事件时间戳;节拍检测阶段,使用 `detect-beats.py` 分析音频文件,提取 BPM、节拍等信息;后期制作阶段,通过 Remotion 项目 `promo/` 渲染视频,包括相机缩放、字幕、开场/结束卡片等。该技能还包含了大量针对 Velxio 应用特殊陷阱的解决方案,例如处理模态框、组件选择器搜索、电路验证器等,确保录制过程的稳定性和视频质量。

兼容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/velxio/velxio_docs/tree/HEAD/skills/velxio-promo-video

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Velxio 宣传视频制作管道

分为三个阶段,全部在此仓库中(velxio_docs; 开发机上位于 /home/dave/velxio_docs):

  1. 录制 — scripts/promo-record.mjs 驱动 staging 环境上的真实产品,执行端到端操作(空白项目 -> 选择 ESP32 -> 添加 220R 电阻 + LED -> 旋转电阻器 -> 通过引脚点击连线 -> 编写草图 -> 运行 -> LED 闪烁),并注入可见光标和点击涟漪。每个关键步骤都会记录 {t, x, y, label} 到 scripts/promo-events.json;原始视频保存到 scripts/promo-raw.webm。
  2. 节拍网格 — scripts/detect-beats.py(librosa)将音轨转换为 promo/src/beats.json(包含 BPM、节拍、军鼓、低音鼓)。
  3. 后期制作 — 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:峰值必须在点击之前到达,以便画面显示卡片仍处于打开状态,然后释放动画揭示零件的放置位置。如果在点击时达到峰值,则缩放会停留在一个已经关闭的对话框上。

陷阱(每个都曾导致一次失败的录制 —— 所有问题现在均已由脚本处理)

  1. / 即使在登录后也是营销着陆页;编辑器位于 /editor。首先通过 fetch 在页面内进行 POST /api/auth/login 来完成登录。
  2. 在全新的 /editor 上,“开始新项目”覆盖层会自动打开(.new-project-overlay),并拦截所有外部指针点击。首先与之交互,或以编程方式派发点击事件。
  3. 选择器的搜索输入框保留之前的查询条件 —— 在输入新内容之前,使用 Ctrl+A + 退格键清除,否则你会搜索出“esp32led”。
  4. 选择器卡片:通过 .component-picker-modal .card-name 匹配精确标题(通用的文本引擎可能会命中模态框后面的 Monaco 令牌)。结果会进行防抖处理 —— 最多轮询 5 秒。卡片名称是精确的(例如“Resistor 220 Ω”使用 U+2126 风格字符,而非“Resistor”;请检查 /components-metadata.json)。
  5. 开发板不要通过拖拽其主体移动 —— 将开发板保持在选择器放置它的位置(靠近画布右边缘),并相对于其实时边界框将小组件放置在开发板左侧,那里有空间。
  6. 引脚点击:使用应用自身的 [data-pin-overlay="true"][title=<pin>] div 元素,并选择最接近宿主元素的候选者(标题可能冲突:开发板引脚“2” vs 电阻器引脚“2”)。根据 pinInfo 偏移计算位置在旋转的零件上会失败。ESP32 引脚命名为 '2'、'4'、'GND'(而非 D2)。
  7. 通过计算 path[stroke="#1a1a1a"](每条导线的轮廓路径;导线没有类或 data 属性)来验证每条导线是否已连接。如果失败,则通过按 Escape 键并重新点击来重试一次。
  8. 电路验证器会阻止没有串联电阻的 LED 运行(会报 3.9e12 A 错误)。演示必须连接 GPIO2 -> 220R -> LED 阳极,GND -> LED 阴极。切勿发布需要点击“仍然运行”的录制内容。
  9. 空白模板附带一个默认草图 —— 在输入屏幕上的注释之前,先按 Ctrl+A,然后通过 monaco.editor.getModels()[0].setValue(...) 设置完整的草图(逐字打字会与 Monaco 的自动闭合括号功能冲突)。
  10. “喜欢 Velxio?/ 在 GitHub 上为我们加星”的 Toast 通知会在录制时间超过约 5 分钟时干扰画面 —— 注入的清理脚本每秒会将其移除一次。
  11. Playwright 不录制操作系统光标:注入的 #vx-cursor div 以及鼠标按下涟漪(context.addInitScript)是可见的指针。
  12. 编译等待是真实存在的(热启动 30 秒 - 冷启动 5 分钟):录制器记录 run 和 sim-started;prepare.mjs 会拼接掉这段间隔。模拟开始通过“浏览器内”控制台行检测到;“guest crashed”表示应中止。
  13. Remotion 通过 --browser-executable 参数使用 Playwright 自带的 Chromium 进行渲染(此机器上没有下载额外的捆绑浏览器)。

参考仓库(2026-08-15 审查)

两个用于相同类型的 Claude-Code 技能,但采用不同的方法:它们从截图/原理图 UI 合成影片,并使用合成光标 —— 我们的方法录制真实产品。在技能升级时可以克隆它们:

  • github.com/noamdorr/saas-product-demo-video —— 在 Remotion 中制作 20-45 秒节拍同步的营销影片。值得借鉴:音轨节拍同步(librosa detect-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 中跟踪。

相关技能