dyachkovp/product-motion

Product Motion

制作展示功能介绍的短视频：产品界面居中、光标点击、文字键入、元素逐级显现、卡片级联弹出、镜头引导视线、旁白解说操作过程。此方法已在多个产品视频中得到验证；此处已与特定品牌解耦。

原则

1. 帧即时间的函数。 视频是一个 HTML 页面，其中 render(t) 根据时间计算帧状态，scripts/render.py 逐帧捕获并传递给 ffmpeg。不使用 CSS 动画、定时器或屏幕录制：无卡顿或不同步，任何时刻均可通过单帧验证。引擎为 templates/engine.js（references/engine.md）。
2. 只展示产品中已有的内容。 界面、文字、状态均来自当前项目的代码、原型、docs/ 或屏幕截图。视频中不含不存在的功能。数据使用虚构的简短名称。为场景虚构的内容（回复、状态文本）会告知用户以进行核对。
3. 风格来自产品，而非本技能。 颜色、强调色、字体、标志均来自项目的品牌配置文件（motion/brand/），该配置从项目代码中提取（references/brand.md）。本技能的默认配置文件仅用于草稿。
4. 我们不自行合成语音。 本地 TTS 听起来像机器人。用户将获得用于 Gemini TTS 的文本和提示词（或自行录音）并发送文件；align_vo.py 将音频按词语对齐。在此之前，视频仅包含字幕和音乐。
5. 先看帧，再渲染。 在完整渲染前，提供选定格式关键帧的联系表，并通过 verify_scene.py 进行校验。在帧阶段捕获构图错误成本最低。
6. 不猜测用户意图。 语言、格式、加速、音乐、发布方式均来自简报或问题。如下默认值仅在用户未说明时使用。

流程

0. 环境（每台机器一次）

python3 <skill>/scripts/check_env.py

需要 Python 3.9+、ffmpeg/ffprobe、pip install playwright numpy scipy pillow（+ faster-whisper 用于配音）、python -m playwright install chromium；加速版本需要带有 rubberband 的 ffmpeg。建议在项目的 venv 或附近目录中安装；未经用户同意不要自行安装依赖——请提示命令。

1. 简报

功能；时长（未说明则单个功能 30–35 秒，板块 60–75 秒）；受众与用途（教程、宣传片、投资者、落地页）；语言；格式（未说明则提供 16:9 和 9:16 竖版供选择）。一次不超过两个问题；其余内容采用合理默认值，并在回复中说明。详细说明见 references/brief.md。

2. 功能详情——从当前项目获取

阅读功能的代码和原型、docs/、屏幕截图：界面、精确的文字、占位符、按钮、状态、哪些存在哪些不存在。如果不清楚用户在主要操作后看到什么，请询问。

3. 品牌配置——每个项目一次

如果项目中不存在 motion/brand/，则根据 references/brand.md 创建：brand.css（来自 CSS 变量、主题、tailwind 配置的 token）、本地字体（已验证授权）、标志。在第一个视频前向用户展示一个示例帧。后续视频直接使用已有的配置。

4. 故事板

表格：时间码 · 画面内容 · 镜头/动画 · 台词（references/storyboard.md：按时长提供的骨架，文字密度 1.3–1.6 词/秒，场景原型）。视频长于 30 秒或简报不完整时，显示表格并等待用户确认“可以”；短视频且简报清晰时，可直接组装并在显示表格的同时展示首帧。

5. 视频项目

如果项目中已有存放视频的目录（如 promo/、design/motion/ 等），则放在那里；否则放在 motion/<slug>/。

python3 <skill>/scripts/new_project.py motion/<slug> --brand motion/brand --lang ru --title "功能 · 产品"

包含：video.html、plan.js、cues.js、tmap.js、engine.js、processing.js、base.css、brand/、build/、out/、README.md。build/ 和大型 out/*.mp4 应加入项目的 .gitignore，除非用户另有决定。如果项目中有 docs/，则添加一个指向视频及其 README 的简短链接。

6. plan.js 和场景

plan.js 是唯一数据源：duration、fps、canvas、language、product、audience、hold、语音提示 vo[]（id、at、text、tts、subs）、pronounce、emphasis、music。window.PLAN = 后为严格的 JSON。

在 video.html 中，将演示内容替换为实际功能界面：build（重复元素）、setup（E.measureAt + E.rect 测量、两种格式的相机关键帧、光标、点击）、scene(t)。屏幕事件应与语音提示的词语同步（E.sync('p3:слово', 备用)）。暗色界面和模态框通过 E.dim() 和 #app2 实现。场景配方见 references/scenes.md，运动与相机规则见 references/motion.md。使用滑块预览：video.html?preview=1，通过 python3 -m http.server 在视频目录中启动。

7. 帧校验

python3 <skill>/scripts/verify_scene.py video.html --fmt both
python3 <skill>/scripts/render.py video.html stills --fmt both --times 1,6,9,12,15,19,23,27,31,34 --sheet

打开 build/stills/sheet_h.jpg 和 sheet_v.jpg：相机对准动作；标签位于对应片段下方；文本无换行或截断；强调色仅在指定位置；“处理→结果”切换处无白色闪烁；9:16 格式文本足够大，字幕位于底部面板之上。调整至关键帧无误。首次渲染前阅读 references/pitfalls.md。

8. 配音

python3 <skill>/scripts/vo_pack.py plan.js            # --model 3.8 用于 Gemini 3.8 Flash TTS, --voice female

以两个独立的代码块提供 out/voiceover/tts_text.txt 和 tts_prompt.txt（文本放在文本字段，提示词放在样式字段）、语音（俄语男性建议首选 Schedar）、要求一次性完整录制以及来自 timing.md 的表格。用户也可以使用同一文本自行录制。规则见 references/voiceover.md。

9. 配音到达 → 对齐

python3 <skill>/scripts/align_vo.py plan.js voice.wav        # build/vo_aligned.wav, cues.js, out/subtitles.srt, 报告

阅读 build/align_report.md：将标记为“需人工校验”的词语连同时间码告知用户；偏移的语音提示最好在 plan.js 中修正。如果语音在最后一帧（hold）之后仍未结束，脚本将停止。

加速仅为建议。 如果视频感觉“拖沓”，建议使用 retime.py（朗读速度 +4.5%，更短的停顿，为视频、语音、音乐和字幕使用统一时间映射）。仅在用户同意后才执行加速。

10. 音乐、混音、渲染、组装

python3 <skill>/scripts/music.py plan.js --out build/music.wav                         # 根据 music 部分合成草稿音乐
python3 <skill>/scripts/prepare_music.py plan.js track.mp3 --end-align --out build/music.wav   # 或使用用户提供的曲目
python3 <skill>/scripts/mix.py build/music.wav build/vo_aligned.wav --out build/mix.wav
python3 <skill>/scripts/render.py video.html video --fmt h --out build/h_subs.mp4
python3 <skill>/scripts/render.py video.html video --fmt h --qs subs=0 --out build/h.mp4
python3 <skill>/scripts/assemble.py --video build/h.mp4 --audio build/mix.wav --out out/<slug>_16x9.mp4
python3 <skill>/scripts/assemble.py --video build/h_subs.mp4 --audio build/mix.wav --out out/<slug>_16x9_subs.mp4
#   ... 如果简报中包含竖版，则对 --fmt v 执行相同操作（_9x16，_9x16_subs）
python3 <skill>/scripts/verify_media.py plan.js out/*.mp4 --sheet

渲染速度约为每分钟视频 2–5 分钟（取决于格式）——请在后台或分段执行（--start/--end，使用 assemble.py --video part1 part2 … 拼接）。合成的音乐是临时的；对于公开视频，建议使用授权曲目。详情见 references/audio.md。如有要求，使用 export_web.py（纯净 MP4、WebVTT、海报图、最终帧）生成用于网站播放器的文件；未经用户单独决策不得执行发布。

交付给用户的内容

• 选定格式的文件：<slug>_16x9.mp4、<slug>_16x9_subs.mp4（+ _9x16）、SRT、配音包（在录音之前）、联系表。提供文件路径；如有文件发送工具，请使用它发送。
• 简要说明：时长、各场景内容；哪些内容是虚构的并需要与产品核对；音乐为临时；哪些内容未经验证（例如未人工试听）。
• 更新视频文件夹的 README：状态、简报决策、如何重新构建。
• 不重述流程，不宣传“革命性 AI”。

技能文件

templates/engine.js	帧引擎：相机、光标、点击、暗化与上层 #app2、字幕（subs=0）、时间映射 tmap.js、预览 preview=1、测量、markup/grad/plural
templates/base.css	基于品牌 token 的组件：头部、渐变输入框、标签、提示、暗色处理、输出、弹出框、聊天、评分、结尾
templates/brand/	默认品牌配置：brand.css、Manrope（OFL）、占位标志
templates/processing.js	默认处理动画（环形、强调色光晕、飞入卡片）
templates/starter.html、plan.js	一个约 36 秒的演示视频“智能搜索”，用于虚构产品 Demo：吸引注意 → 带标签输入 → 提示 → 处理 → 带“为什么”的输出 → 保存 → 评分 → 结尾
scripts/	check_env、new_project、verify_scene、render、vo_pack、align_vo、retime、music、prepare_music、mix、assemble、verify_media、export_web
references/	brief.md · brand.md · storyboard.md · scenes.md · motion.md · engine.md · voiceover.md · audio.md · pitfalls.md