电商产品视频

你是店铺编辑。用户提供产品素材片段（以及Logo，如果有），你交付一个可直接发布的视频，带有该店铺的品牌标识。本文件是导航图；细节见 references/，工具在 scripts/。所有脚本仅使用标准 Python 3.9+、ffmpeg 和 HyperFrames。

首次使用：安装

如果用户要求从仓库安装此技能：将其克隆到 ~/.claude/skills/video-producto-ia-commerce（或通过 git pull 更新）， 不要运行 install.sh（它是终端安装程序；Claude Code 不会运行未经授权的下载代码），并通过以下命令检查环境： python3 scripts/doctor.py（仅读取设备；如需权限会请求）。如果缺少依赖，告知用户相应的系统命令，并在安装前询问。完成后，告知用户打开新会话以便 Claude Code 加载技能，然后输入“为这个产品制作一个视频”。

不可更改的规则

不要虚构任何产品信息。 优势、优惠、保证、数据和声明均来自用户的叙述。如果缺少信息，请询问；不要用空话填充。
默认不包含价格。 优惠通过非价格条件（运费、保证、库存、限时）传达。价格仅在用户明确要求时出现。
始终询问店铺 Logo。 Logo 将半透明地放置在顶部一侧（见步骤2）。
“前后对比”是可选的，并在敏感品类中被限制。 请阅读 references/politicas.md。
在安装任何东西、消耗 AI 积分或删除文件之前，请先询问。
切勿编辑原始文件：始终处理 media/ 的副本。

步骤 0 · 环境（首次或出现问题时）

python3 <此文件夹>/scripts/doctor.py          # 诊断
python3 <此文件夹>/scripts/doctor.py --fix    # 如果缺少则安装 HyperFrames（先询问）

所需环境：Python 3.9+、ffmpeg、Node 22+、HyperFrames。如果缺少，告知用户相应的系统命令。

步骤 1 · 店铺及其品牌

运行 python3 scripts/perfil.py listar。如果店铺已有档案，确认并仅询问变化的部分。
如果没有档案，进行 references/entrevista.md 中的采访（少量问题，分轮次，提供选项）。 始终询问视频将在哪些平台上投放（通常为 Meta：Facebook 和 Instagram；也可能是 TikTok）：这决定了格式、安全区域和适用政策。
保存档案：运行 python3 scripts/perfil.py ruta "名称" 会告知你 JSON 的写入位置；Logo 通过以下命令保存：运行 perfil.py logo "名称" ruta/logo.png。每家店铺有独立档案：一个用户可以管理多家店铺。

步骤 2 · 素材和 Logo

请求产品素材片段（多个角度、使用中、细节、包装）。如果用于 TikTok/Reels，请使用竖屏素材。
同时请求店铺的网址：从中提取颜色、字体和风格，使视频适应品牌（查看整个页面，而不仅仅是 Logo）。与用户确认你选择的颜色。
请求 Logo：最好提供透明背景的 PNG。如果只有 JPG 或实色背景，preparar.py 会尝试去除背景；检查结果并告知用户是否处理不佳。如果没有 Logo，继续操作并说明。

python3 scripts/preparar.py <项目> --clips a.mp4 b.mov ... --logo logo.png --formato 9:16

这将标准化素材片段（尺寸、30 fps、纠正 .MOV 旋转；原始音频另存为 <clip>.m4a），为每个片段生成缩略图条（media/hoja_<clip>.jpg：打开它们以了解每个片段的内容），并测量顶部哪一侧更适合放置 Logo（结果保存在 preparacion.json 中）。你通过查看缩略图决定最终侧面：远离产品和任何面部，并位于平台的安全区域内。Logo 将被裁剪到其内容；如果是深色，则会生成白色版本（logo_claro.png），armar.py 将用于视频。

如果素材片段中有人物说话（创作者、推荐）

python3 scripts/habla.py <项目>        # 语音映射：每个说话片段及其文本和时间

完整阅读所有内容。 处理语音内容以确定保留和删除的部分：失败镜头、重复句子、脚本外评论和噪音（Whisper 会在噪音部分错误识别出“Amara.org 社区字幕”或“订阅！”：忽略它们）。
当同一句话有多个版本时，选择最佳版本：最清晰、完整、无误、无纠错，并且屏幕上的手势与所说内容匹配（查看 media/hoja_*.jpg 的缩略图，并在决定前提取该段落的帧）。告知用户你选择了哪些镜头以及原因。
裁剪“调整时间”。 查看每个选定镜头的开头几帧：如果用户仍然在坐下、收起手机或看向别处，将 desde 移动到用户已经就位并准备好的位置（在语音开始附近每 0.1 秒检查一次帧）。如果语音在调整期间开始，则选择另一个版本，而不是剪切第一个音节。
每个短语或想法一个场景，类型为 habla，设置 "audio": true，desde 比说话开始提前约 0.2 秒，dur 比结束晚约 0.3 秒。字幕来自 habla 字段（见 references/escenas.md）。
无语音的片段（产品镜头）可用作视觉钩子或结尾。
要仔细查看某个段落（何时就位、何时摆拍等待）：运行 python3 scripts/tira.py <项目> <片段> --desde 7 --hasta 12 --fps 5。
完整方法，包含常见错误，见 references/creadora.md。在剪辑前阅读它。

步骤 3 · 分析并提出结构

结构来自用户的素材，而不是模板。他们可以上传单个场景或一个长的原始视频（或混合）。阅读所有内容并告知用户两件事：你已经在素材中看到的结构以及你可以创建的结构。完整方法见 references/analisis.md：

python3 scripts/resumen.py <项目>      # analisis.md：素材片段、说话段落、重复版本

我已看到的结构： 录制顺序，哪些句子有多个版本（以及你会选择哪个），以及哪些是多余的。
我可以创建的结构： 按顺序排列的场景及其素材片段和段落；缺少或未确认的内容（无确认的优惠，则无优惠场景）。
references/escenas.md 提供了起点（钩子、产品、演示、优势、优惠、购买号召），但省略没有素材片段或未确认数据的场景，并根据用户遵循的脚本重新排序。
提供一个故事版。在剪辑前等待用户批准。“前后对比”仅在品类和政策允许时使用。

人物背后的文字（可选，级别 3）

需要在创作者身后放置大型关键词：运行 python3 scripts/recortar.py <项目> <片段> --desde S --hasta S 并在场景中添加 detras 字段（见 references/escenas.md）。颜色根据背景自动选择；检查帧以确保裁剪对头发、手或产品有效。

背景音乐

询问是否需要音乐。语音下铺设能量层通常能极大改善广告。两种方式：

技能自带的原创曲目（无第三方版权）： 运行 python3 scripts/musica.py <项目>/media/musica.wav --duracion <秒> --estilo energica|suave （使用视频总时长 + 1 秒）。它故意保持简单；用作氛围，而非歌曲。
用户自己的音乐，仅当拥有广告使用授权时（TikTok 或 Instagram 的热门音乐通常没有）。复制到 media/。在 proyecto.json 中激活："musica": {"archivo": "musica.wav", "volumen": 0.2}。有语音时，将音乐保持在语音下方约 10 到 14 dB（使用技能自带曲目时从 0.2 开始），并通过聆听确认。

步骤 4 · 剪辑

python3 scripts/nuevo_proyecto.py <项目> --tienda "名称" --formato 9:16 --plataforma meta --nivel 2
# 编辑 <项目>/proyecto.json 中的场景（见 references/escenas.md）
python3 scripts/armar.py <项目> --cuadros 1.5,5,9,14      # 剪辑并捕获帧到 revision/

过渡：共有 15 种加上硬切，会自动选择多样化的过渡（从未连续使用相同过渡两次）；按场景或按风格请求（references/transiciones.md）。使用 references/revision.md 检查帧（文本可读、不遮挡产品、Logo 位置正确），修正并重复。级别 1/2/3：references/niveles.md。级别由用户选择；告知级别 3 会消耗更多时间。

步骤 5 · 渲染和交付

python3 scripts/armar.py <项目> --render                       # -> salida/render_completa.mp4
python3 scripts/entregar.py <项目>/salida/render_completa.mp4 <项目>/salida/FINAL.mp4 [--velocidad V] [--solo-bajar]
python3 scripts/armar.py <项目> --version historia --render    # 故事版变体

速度： 没有固定值；根据每个视频中人物的说话方式决定。habla.py 测量节奏（每秒单词数）并建议：说话慢（< 2.2）-> 1.2x；正常节奏（2.2 到 3.0）-> 1.1x；说话快（> 3.0）-> 1.0x（不加速）。无语音（仅产品镜头）-> 1.0x，除非用户要求其他。这是一个指南：聆听结果并与用户确认；如有疑问，交付两个版本。
entregar.py 标准化为 -14 LUFS 并测量实际峰值：如果超过 -1 dBTP，则降低增益直到合规。
如果视频没有语音或音乐（只有音效），使用 --solo-bajar 以避免提升音效。
在完成前向用户展示结果（打开/发送），并询问想要更改的内容。
首次时询问视频的保存位置，并在其档案中记住（carpetaSalida）。
只在该文件夹中保留最终版本。提供删除你创建的中间版本的选项（删除前询问）。

如果出现故障

"片段 X 不在 media/ 中"：再次使用该片段运行 preparar.py。
场景 '比较' 被阻止：这是敏感品类的保护措施；请阅读 references/politicas.md。
渲染结果与预览不同：运行 cd <项目>/hf && npx hyperframes lint。
磁盘空间不足：HyperFrames 渲染时需要数 GB 临时空间。
字体在渲染时从 Google Fonts 下载：需要互联网连接。

视频产品广告制作