Communitygithub.com

autoDemoRecordingSkill

自动录制 Web 应用的演示视频(带配音或无配音),支持多种语言和本地/远程语音引擎。

autoDemoRecordingSkill 是什么?

该技能能自动将 Web 应用的操作过程录制为精美的演示视频。你只需编写一个 **故事文件 (story file)**,描述要展示的内容和旁白文本,脚本会自动完成录制、帧绘制、编码、配音和质量检查。视频可无配音,也可选择普通话、英语、日语、韩语、德语、法语、西班牙语、意大利语、葡萄牙语或俄语配音。配音引擎可选用本机 GPU 上的 Qwen3-TTS、本机任意 CPU 上的 Kokoro,或用户提供的远程 API(兼容 OpenAI、ElevenLabs、阿里云 DashScope)。最终输出 1920×1080 60fps 的 MP4 视频,包含摄像机移动、高亮、编号步骤、字幕和章节。技能在 Linux、Windows 和 macOS 上均可运行,并兼容 Claude Code 和 Codex 代理。

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/OrrrGE/autoRecording/tree/main

在你喜欢的 AI 中提问

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

文档

autoRecording

将 Web 应用转化为完整的演示视频。你编写一个 故事文件,描述要展示的内容和要说的旁白;脚本负责录制、绘制、编码、配音和质量检查。视频可以是无声的或有配音的,支持普通话、英语、日语、韩语、德语、法语、西班牙语、意大利语、葡萄牙语或俄语,由本地模型(GPU 或 CPU)或用户提供的远程服务生成语音。

story.py ──demo_record.py──► timeline.json + frames/*.jpg
                                  │
                           demo_render.py ──► silent.mp4  (1920×1080, 60 fps)
                                  │
                           demo_voice.py  ──► silent-配音版.mp4 / silent-narrated.mp4   (可选)

0. 开始前务必先确认

在回答以下问题之前不要开始录制。在 Claude Code 中使用 AskUserQuestion;在 Codex 或其他代理下,用普通文字提问并等待回复。

  1. 是否需要配音? 无声视频,或带语音旁白。如果用户不需要配音,跳过所有配音步骤;无声视频就是交付物。
  2. 旁白语言(以及字幕语言,字幕就是旁白念的脚本):普通话 / English / 日本語 / 한국어 / Deutsch / français / español / italiano / português / русский。默认:应用语言和用户编写语言。
  3. 引擎。 仅提供本机实际可用的选项——先运行 python3 scripts/demo_env.py,仅提供它列出的可用引擎:
    • 本地 Qwen3-TTS(本机 GPU):最佳质量;需要约 6 GB 空闲显存的 NVIDIA GPU 和 Qwen 模型。
    • 本地 Kokoro(本机 CPU):无需 GPU,可在 Windows 和 macOS 上运行;普通话和英语效果良好;声音是固定的(无法克隆)。
    • 远程 API:用户提供提供商(兼容 OpenAI 的端点包括自托管、ElevenLabs 或阿里云 DashScope Qwen-TTS)、密钥,以及可选的 base URL、模型和声音 ID。 经验法则:本地模型已就绪 → 使用它;用户提供了 API 密钥 → 使用 API;两者都没有 → 询问是否安装 Kokoro(下载体积小)或选择无声。
  4. 声音,如果引擎有选择:提供 3-5 种声音,每种一行(例如 Qwen serena / ryan,Kokoro zf_039 / zm_013 / af_maple,OpenAI 声音 ID),并给出合理的默认值。

将答案写入故事文件——LANGUAGE 和 VOICE = {'engine': …, 'speaker': …} — 以便可以重新制作相同的视频。远程密钥永远不要写入故事:将其放在环境变量或 demo_env.py key 中。

不可妥协的原则

  1. 切勿录制用户的在线服务或真实数据。 在其他端口上启动一个带有独立数据目录的临时实例(故事文件中的 launch()),或使用专门的演示数据集。如果应用无法隔离,请询问。
  2. 用数字检查,而不是看画面。 demo_render.py --check 和 demo_voice.py check 是真理的来源。当任何一个报告 注意: 问题时,不要声称视频已完成。
  3. 不要触碰正在运行的服务。 如果选择的端口已被监听,选择另一个端口;永远不要停止他人的进程。
  4. 旁白是可选的,引擎由用户选择。Qwen 需要 NVIDIA GPU;Kokoro 可在任何 CPU 上运行;远程服务需要密钥并将字幕文本发送到该服务——使用前请告知用户。

布局

SKILL.md                  本文件
scripts/demo_env.py       检查机器;创建技能的 Python 环境;获取模型;记住密钥
scripts/demo_record.py    驱动应用并录制帧 + 时间线
scripts/demo_render.py    绘制和编码无声视频;数字检查
scripts/demo_voice.py     旁白:文本行、锚点、录制、试听、构建、检查
scripts/demo_tts.py       引擎:Kokoro (CPU) 和远程服务
scripts/demo_text.py      字幕的朗读、计数和比较方式,按语言区分
scripts/demo_common.py    共享路径、设置、浏览器、密钥
story_template.py         复制此文件为应用编写故事
示例/selftest/            一个页面和两个故事(中文 story.py,英文 story-en.py)
references/               环境.md、导演.md、旁白.md、引擎.md

以下所有命令均相对于此技能的目录执行;在 Windows 上将 python3 替换为 py -3(或 python)。通过克隆到 ~/.claude/skills/autoDemoRecordingSkill(Claude Code)或 ~/.agents/skills/autoDemoRecordingSkill(Codex)将其安装为个人技能。

1. 检查机器

cd ~/.claude/skills/autoDemoRecordingSkill
python3 scripts/demo_env.py            # 只读:显示已安装什么、缺少什么、如何获取、哪些引擎可以说话
python3 scripts/demo_env.py setup      # 录制/渲染/检查所需的包(几百 MB)
python3 scripts/demo_env.py setup --models   # + Whisper large-v3 和 CAM++ 检查(约 3 GB)
python3 scripts/demo_env.py setup --kokoro   # + Kokoro,CPU 语音(约 400 MB)

对于 Qwen 引擎,还需要准备一个带有 CUDA torch 和 faster-qwen3-tts 的 Python 环境,以及两个 Qwen3-TTS 1.7B 模型;对于远程引擎,使用 python3 scripts/demo_env.py key openai=…(或环境变量)记住一次密钥。记录每个非默认路径一次:

python3 scripts/demo_env.py set chromium=/path/to/chromium tts_python=/path/to/python \
    tts_custom=/path/to/Qwen3-TTS-12Hz-1.7B-CustomVoice tts_base=/path/to/Qwen3-TTS-12Hz-1.7B-Base

技能自身的文件位于 ~/.cache/auto-demo-recording(可通过 AUTO_DEMO_HOME 覆盖)。references/environment.md 包含 Windows、macOS 和 Linux 的详细信息。

2. 用自测验证安装

PY=~/.cache/auto-demo-recording/venv/bin/python
S=~/.claude/skills/autoDemoRecordingSkill
$PY $S/scripts/demo_record.py --story $S/examples/selftest/story.py --work /tmp/demo-selftest
$PY $S/scripts/demo_render.py --work /tmp/demo-selftest --check
$PY $S/scripts/demo_render.py --work /tmp/demo-selftest --out /tmp/demo-selftest/selftest.mp4
$PY $S/scripts/demo_voice.py --work /tmp/demo-selftest      # 仅在需要旁白时执行

story-en.py 是相同的测试,但使用英文字幕和英语旁白路径。录制会打印 JSON 摘要(时长、帧数、浏览器、错误)。selftest.mp4 应为 1920×1080、60 fps、时长约 64 秒。

3. 编写故事

将 story_template.py 复制到应用旁边(或任何地方)并填写。其约定如下:

名称含义
TITLE, SUBTITLE, CHAPTERS顶部横幅中的文本;章节也会在页面上绘制
LANGUAGE字幕和旁白的语言(zh, en, ja, ko, de, fr, es, it, pt, ru)
VIEW, DENSITYCSS 像素下的页面大小和设备缩放比例;宽度/高度必须为 64:31
PORT临时实例的端口
LOOK{'accent': '#2f6fed', 'note': '#ee5c18', 'fast': '快进'} — fast 是字幕栏中的语言
VOICE旁白:engine, speaker,对于远程服务还包括 model / base_url(永远不要包含密钥);见 references/engines.md
READING字幕的朗读速度;默认值:该语言自身的速度(普通话为 5.5 字符/秒)
launch(work, port){'command': [...], 'url': ..., 'env': {...}, 'wipe': [...], 'cwd': ..., 'ready': ..., 'timeout': ...};或者改为定义 URL
guard(d)可选;如果页面未处于预期的初始状态,则提前失败
story(d)实际的导演指令:await d.say(...), await d.click(...) 等

d 对象是导演。其完整 API、时间模型、标记/放置规则和常见模式在 references/director.md 中。在编写故事之前阅读该文件;本文件的其余部分仅介绍工作流程。

编写一个好故事的经验法则:

  • 每个字幕一个想法;说明观众应该注意什么,以及页面实际显示的结果。
  • 优先使用 d.say() 然后 d.read() 再继续;字幕同时也是旁白脚本。
  • 用 LANGUAGE 语言编写字幕。对于无声视频,它们仍在屏幕上阅读,因此保持简短。
  • 为点击编号(await d.click(locator, '添加')),仅标记重要的内容。
  • 长时间等待使用快进(await d.until(..., speed=4))而不是剪切。

4. 录制

$PY $S/scripts/demo_record.py --story /path/to/story.py --work /tmp/demo-work --quick
$PY $S/scripts/demo_record.py --story /path/to/story.py --work /tmp/demo-work

--quick 是快速试用:它跳过观看者暂停,只等待应用。用于捕获选择器和状态错误。随后进行实际录制;work/timeline.json 会被覆盖,旧帧会被删除。

在录制之前,脚本仅清除 frames 和 wipe 中列出的路径,检查端口空闲,从故事文件启动命令,并等待应用响应。应用的日志位于 work/server.log。在 Windows 上,应用及其启动的所有内容都会通过 taskkill /T 停止;在其他系统上,整个进程组会被停止。

5. 检查和渲染

$PY $S/scripts/demo_render.py --work /tmp/demo-work --check
$PY $S/scripts/demo_render.py --work /tmp/demo-work --out /tmp/demo-work/demo.mp4

--check 在不查看画面的情况下验证:标记区域非空且颜色与 expect 匹配,标签不覆盖页面内容,框在摄像机内部,步骤/点击可见,字幕适配,字形在字体中存在。修复故事或时间安排后重新录制。渲染还会比较采样输出帧与绘制的帧,并将结果写入 work/render.json。

如果用户不要配音,则无声视频就是交付物——在此停止并报告。

6. 配音(仅在要求时执行)

$PY $S/scripts/demo_voice.py --work /tmp/demo-work            # 所有步骤
$PY $S/scripts/demo_voice.py lines --work /tmp/demo-work      # 先检查发音/时间

它将配音视频写在无声视频旁边:中文为 <name>-配音版.mp4,其他语言为 <name>-narrated.mp4。步骤是可恢复的:参考片段 → (Qwen: 试读) → 录制 → 语音/说话人检查 → 选择/适配/混合 → 验证。阅读 references/narration.md 了解设置、发音修正和紧凑的文本行,以及 references/engines.md 了解引擎、声音、密钥和成本。最终 check 必须显示 没有发现问题;任何 听写有出入 行意味着语音说了其他内容——修正字幕,添加 say 覆盖,重新录制该行,或选择其他声音。

7. 报告

向用户提供输出路径(无声视频和,如果要求了,配音视频)、时长、分辨率/fps、字幕/标记数量、配音引擎和声音,以及配音检查结果。提及任何剩余的 注意: 警告,并且永远不要隐藏失败的检查。

故障排除第一步

  • 缺 … → 运行 python3 scripts/demo_env.py 并按照 → 行操作。
  • 端口已被占用 → 更改故事中的 PORT;不要停止现有的服务。
  • 点不到这个元素 → 元素被覆盖或位于屏幕外;先滚动/缩放,或选择其他目标。
  • 页面宽度不匹配 → 页面在 VIEW 尺寸下未响应;调整 VIEW 或页面,保持 64:31 比例。
  • 配音行太紧凑 → 缩短该字幕或为其分配更多时间,然后重新录制。
  • Kokoro 的词表里没有这些词 → 这些词会被 Kokoro 跳过;在字幕的拼写中将它们添加到 VOICE['say'] 中(例如 `

相关技能