Communitygithub.com

产品解说视频

将任何软件项目(GitHub 仓库、本地文件夹、爬虫、自动化脚本、机器人、网站、CLI、API 或整个工具集)转化为带有 AI 配音、字幕和音乐的定制动画解说视频。

产品解说视频 是什么?

此技能用于将任何软件项目(如 GitHub 仓库、本地目录、网站、CLI 工具或 API)自动转化为高质量的动画解说视频。它首先分析项目代码以提取真实信息(功能、命令、路由等),然后根据项目特性设计独特的视觉隐喻和动画(非固定模板),并生成包含布局审核、神经语音配音和背景音乐的视频。支持输出横屏或竖屏的 MP4 文件、SRT 字幕文件以及可嵌入 HTML 播放器。该技能适用于演示视频、产品推广、README 引导视频、社交媒体短片等场景,能帮助非技术用户快速理解项目的核心功能。它主要运行在支持 Python 和 Playwright 的环境中,需要安装 ffmpeg 等依赖,并优先使用 ElevenLabs、OpenAI TTS 或 Edge 语音引擎进行配音。

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/cheransanketh070-afk/claude-explainer-skill/tree/HEAD/product-explainer-video

在你喜欢的 AI 中提问

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

文档

产品解说视频 是做什么的?

用户指向他们构建的项目;你返回一个带有语音配音的精美动画解说视频,让一个陌生人能在不到一分钟内理解。视频必须为这个项目量身定制:它自己的视觉隐喻,它自己的专属动画。绝不制作一个只是替换名称的通用模板视频。

分析(事实)→ 设计简报 → storyboard.json(内置 + 自定义场景)→ 验证 → 联系表 QA → 修复 → 渲染(+语音,+音乐)→ 交付

脚本位于此文件旁边的 scripts/ 目录中。$SK = 此技能文件夹(此 SKILL.md 所在的位置)。

0. 环境检查(10 秒)

python3 -c "import playwright, PIL, numpy" && which ffmpeg && python3 $SK/scripts/voiceover.py --list

缺失部分:pip install playwright pillow numpy edge-tts --break-system-packages && playwright install chromium。没有 ffmpeg → 告知用户(MP4 需要它;--html-only 仍然提供 HTML 播放器)。语音合成 --list 显示当前可用的语音引擎。

1. 理解要解释的内容

先推断,少提问:主题(一个产品或一个作品集)、受众/目的(GitHub 上的开发者、客户、社交媒体)、来源(本地路径、上传的 zip、GitHub URL、在线网站或仅需描述)。默认设置:16:9,45–75 秒,开发者加上好奇的非技术观众,语音开启。仅在真正不明确时才问一个简短的问题。否则,用一行陈述假设,然后继续。不要面谈用户。

2. 收集事实(从不跳过:这能保证视频的真实性)

python3 $SK/scripts/analyze_project.py /path/or/git-url [more...] -o facts.json
python3 $SK/scripts/capture_site.py https://their-site.com -o site-capture     # 在线网站:截图 + 页面事实

分析器会输出描述、语言、功能、真实的 README 命令、CLI 标志、路由、联系的域名、输出、环境变量、CI/定时任务以及可安全显示的 真实统计信息。阅读它,然后当信息不足时(核心循环是什么?用户实际运行什么?输出长什么样?)自己阅读 README 和 1–3 个关键源文件。克隆失败或网络不可用 → 要求提供 zip 或 README。网站捕获被屏蔽 → 要求提供截图或用自定义场景绘制 UI。

3. 设计简报,然后是故事板

阅读 references/narrative-playbook.md(叙事弧线、真实性规则)、references/storyboard-schema.md(所有场景类型/字段)和 references/custom-scenes.md(如何编写自定义场景)。assets/examples/ 中的参考故事板展示了好的范例;它们是灵感来源,而非模板:不要重用它们的内容、结构或措辞。

首先确定(简要写下):

  1. 一句承诺。
  2. 产品的物理行为(事物在位置间移动)以及展示它的唯一视觉隐喻。
  3. "顿悟"时刻场景。
  4. 主题、强调色(如果知道则为用户的品牌色)、bg 样式、节奏:与产品个性相匹配。
  5. 哪 2–4 个场景将是自定义的(为此产品绘制)以及哪些通用节拍使用内置组件(标题、问题、步骤、行动号召...)。

然后编写 storyboard.json:

  • 叙事弧:钩子 → 问题 → 工作原理 → 证明其简单 → 具体结果 → 为何优秀 → 行动号召;7–10 个场景,45–75 秒。
  • 质量标准:除非产品确实是一个纯 CLI,否则至少有一个场景是自定义的;顿悟场景始终是自定义的或精心选择的内置场景。机器人展示对话;爬虫展示页面变为行;API 展示请求和响应;仪表盘展示实时数字。
  • 每个场景上的 narration:口语风格,15–35 个词。它会变成语音配音、字幕和 SRT。
  • 仅限事实:命令、标志、功能、路由和数字来自事实或用户。终端输出和表格行可以是说明性的但通用;绝不要捏造基准、客户数量或功能。统计场景仅使用 真实统计信息/README/用户数字。
  • 将 meta.url 设置为仓库/网站,并以一个清晰的操作号召结束。

4. 验证,然后预览再渲染

python3 $SK/scripts/storyboard.py explainer/storyboard.json
python3 $SK/scripts/render_video.py explainer/storyboard.json --contact-sheet

联系表(约 20 秒)运行布局审核(舞台外、裁剪、截断、字幕碰撞文本以及自定义场景的 JS 错误)并写入 explainer-output/contact-sheet.png。查看它并检查:没有内容拥挤或剪切,文本可读,场景彼此明显不同,自定义场景看起来是特意设计的。联系表每场景显示一个后期帧,所以对于每个自定义场景,还要检查一个早期帧和一个中间帧:--still 3.2,6.5。修复并重复直到干净。

5. 带语音渲染

cd explainer
setsid nohup python3 $SK/scripts/render_video.py storyboard.json --quality final --gif \
  > render.log 2>&1 < /dev/null &
sleep 100; tail -c 300 render.log

持续轮询(sleep 100; tail -c 300 render.log)直到出现 DONE。在沙盒环境中,后台工作仅在工具调用运行时推进,因此睡眠轮询驱动渲染;运行时不要结束你的回合。预设:draft(960×540,15 fps),standard(1280×720,30 fps,默认),final(1920×1080,30 fps)。更多 CPU 核心 → 更快(--workers N)。竖屏:meta.aspect: "9:16" 或 --vertical。慢机器:--fps 24。

语音是自动的(--voice auto,默认)。渲染器为每个场景生成一个音频文件,拉伸场景使得叙述永远不会被切断,在语音下压低音乐,并缓存音频以便重新渲染免费。引擎优先级:ElevenLabs(ELEVENLABS_API_KEY)→ OpenAI TTS(OPENAI_API_KEY)→ Edge 神经语音(pip install edge-tts,免费,无需密钥,需要网络)→ Piper(离线神经)→ macOS say → espeak-ng。选项:--voice-name en-US-AndrewNeural(任何引擎的语音名称),--voice-rate +8%(Edge),--voice none 仅音乐,--voice-dir folder/ 使用用户自己的 scene-01.mp3… 文件,meta.voice 将选择存储在故事板中。

如果渲染打印 WARNING voiceover: no speech engine available,视频仍会渲染(仅音乐)并且 voiceover.txt 中有脚本。直接告知用户,并提供一行修复方法:启用网络并 pip install edge-tts(免费),或设置 API 密钥,或安装 espeak-ng;然后重新运行相同的命令(只有语音和编码被重做;播放器和故事板不变)。在 claude.ai 中,沙盒通常没有网络,因此预期会发生这种情况:说明情况,交付静音-音乐视频和脚本,并解释他们可以通过在 Claude Code 中本地运行流水线或设置 API 密钥来添加语音。除非日志显示 voiceover: using '<engine>',否则绝不要声称视频有语音配音。

音乐:生成免版税背景音乐(--mood calm|upbeat|tech 或 meta.music_mood);--music none 或 --music file.mp3。

6. 交付

输出在 explainer-output/ 中:<name>.mp4,<name>-poster.png,player.html(独立的交互式播放器;使用 <iframe src="player.html?embed"> 嵌入;有动画和字幕但没有音频),captions.srt,voiceover.txt,storyboard.resolved.json,voice/,可选的 .gif。

验证:ffprobe -v error -show_entries stream=codec_type -of csv=p=0 <name>.mp4 显示一个音频流;时长匹配;查看海报。将交付物复制到 /mnt/user-data/outputs/ 并 present_files,首先显示 MP4,然后是海报、字幕、player.html 和 storyboard.json(以便他们可以编辑和重新渲染)。保持消息简短:每场景一行,假设了什么,使用了哪个语音引擎,如何调整。仅在有用时提供变体:一个 9:16 的社交剪辑(约 30 秒),不同的语音或品牌色,另一个仓库的视频。

编辑和重新渲染

编辑 storyboard.json(文本、顺序、颜色、自定义场景代码),重新运行联系表,然后渲染。叙述更改仅重新合成已更改的场景。设置场景的 duration 以延长它;它永远不会被缩短到低于动画和叙述所需的时间。

作品集 / "我所有的工具"

在一次调用中分析每个仓库,挑选 3–4 个展示范围的代表作,给每个作品分配一个带有其自身视觉隐喻的自定义或最佳匹配场景,用一个包含其余工具的 features 网格和一个指向个人资料的行动号召来结束。之后提供每个产品的深入视频。

故障排除

  • Playwright is not installed → 步骤 0 命令。
  • 空白/黑色帧或 scene error 行 → 自定义场景的 JS 抛出异常;审核会打印异常。修复代码。
  • 文本被裁剪/截断 → 缩短、删除项目,或制作自定义布局。
  • 语音听起来机械 → 那是 espeak;改为使用 Edge/OpenAI/ElevenLabs/Piper。
  • 语音与场景计时不匹配 → 计时是自动的(场景会拉伸以匹配音频);如果字幕感觉过早,请缩短叙述。
  • 日志不移动 / 渲染被杀死 → 它是在附加模式下运行或没有轮询它;以分离模式重新启动并轮询。
  • 输出太长 → 删除最弱的场景;验证器会在约 90 秒以上发出警告。

诚实的限制

动态图形(图表、终端、代码、UI 模拟、专属动画),而非屏幕录制或逼真画面。对于真实的 UI,传递截图或绘制界面。语音质量取决于可用的引擎。

相关技能