skill-motion：用代码制作动画电影
这种电影是一个JavaScript文件，能在任意时刻在<canvas>上绘制（seek(t)），包含一条音轨（banda.mp3：语音+音乐+音效）以及两者渲染后的MP4文件。制作时间约2小时，ElevenLabs成本仅几美分，可以逐帧修正，并且能在无需网络的情况下在演示文稿中实时运行。
两种模式。 故事模式（角色、漫画或柔和风格，用于情感表达）和商业模式（真实产品、节奏、承诺，用于促进购买）。开始前先决定模式：如果用户提到“营销”、“商业”、“专业”、“演示”或“给客户看”，则阅读references/promo.md并使用assets/motor-promo.js。
| 请求 | 引擎 | 阅读内容 |
|---|---|---|
| 生日、家庭、邀请、角色故事 | motor-base.js（漫画）或motor-suave.js | guion.md, chispa.md |
| 商业广告、网站或应用演示、买家视频、Reels | motor-promo.js + filmar_web.py | promo.md |
| 具有技术感、纪录片镜头风格品牌发布 | motor-tech.js | motor-visual.md 第9节 |
| 倾斜地图、无真实网页的飞行摄像机 | motor-3d.js | chispa.md |
| 解释数字或机制：尺寸、标签、读数、技术图纸 | motor-acotaciones.js（与任何引擎配合使用） | motor-visual.md 第12节 |
| 环绕或遍历3D场景的摄像机镜头 | motor-3d.js末尾的Orbita3D | motor-visual.md 第13节 |
使其成功的关键不是技术，而是三个习惯：所说的一切都是真实的、使用Deepgram聆听而非假设、以及在渲染前通过网格帧检查。Claude在运行时既看不到视频也听不到音频；这两种控制就是它的眼睛和耳朵。
所需环境
Node 18或更高版本、Python 3、ffmpeg和Chrome。语音和音乐需要ElevenLabs账户（ELEVENLABS_API_KEY）。要“听”结果，需要Deepgram账户（DEEPGRAM_API_KEY，可选）。详见INSTALAR.md。
各文件位置
| 我需要 | 文件 |
|---|---|
| 火花：控制清单，让作品达到“哇”而非只是“好”（在写剧本前阅读） | references/chispa.md |
| 概念、已测试风格、台词、角色分配、时间表 | references/guion.md |
| 语音、音乐、音效、混音、使用Deepgram聆听 | references/sonido.md |
| 绘制引擎、角色与姿态、漫画风格、构图规则 | references/motor-visual.md |
| 渲染、轻量版本、演示文稿、发布、git | references/entrega.md |
| .js的起点：漫画风格或柔和风格 | assets/motor-base.js（漫画）, assets/motor-suave.js（柔和，角色会老化） |
| 查看页面和网格帧页面 | assets/pelicula.html, assets/hoja.html |
| 演示文稿内的电影（幻灯片+控制器）和构建器 | assets/pelicula-en-presentacion.html, assets/construir.py |
| 脚本 | scripts/（密钥、语音、音乐、旁白、音效、混音、Deepgram、渲染、轻量） |
| 包含的CC0音效 | sfx/（鸣谢见sfx/LICENSES.md） |
| Canvas上的伪3D（倾斜地图、飞行摄像机、霓虹地面） | assets/motor-3d.js |
| 品牌发布的技术专业风格：纪录片摄像机（HUD）、对焦框、警报、扫描、界面卡片、仪表板、网格地面 | assets/motor-tech.js及references/motor-visual.md第9节 |
| 专业商业广告、产品演示、16:9、9:16和1:1格式 | references/promo.md, assets/motor-promo.js |
| 逐帧使用GPU录制真实网页 | assets/filmar_web.py |
| 客户简报和固定帧数范围的故事板（在绘制商业广告前） | assets/brief-cliente.md, assets/storyboard-plantilla.md, references/promo.md |
弧形光标、点击、输入弹跳、偏移、漂移和摄像机推进。商业广告中所有指针移动都呈弧形，在点击前暂停（cursorPro）；直线移动被禁止 | motor-promo.js（cursorPro, cursor, tecleo, entra, escalonar, deriva, empuje）, references/motor-visual.md第11节 |
| 安全区、矢量界面、“渲染前检查清单”和润色库 | references/promo.md |
脚本中的数字以DATOS块形式呈现，便于单行修订；无音频渲染 | references/entrega.md第11节 |
脚本注释（[VISUAL]、停顿），屏幕上每个数字都带上文字 | references/guion.md第8节 |
| 镜头术语、画幅比例和时间冻结 | references/chispa.md |
| 测量BPM并按小节重排音乐 | scripts/pulso.py, scripts/cortar_musica.py, references/sonido.md第13节 |
| 测试段落、分部分组装、无需重新渲染的新音频 | references/entrega.md第8节 |
| 因产品变更而修改已交付的电影 | references/entrega.md第10节 |
| 使用真人的语音问候并附上传单邀请 | references/sonido.md第9节, references/entrega.md第7节 |
制作流程
按顺序执行步骤；每一步在进入下一步前都有检查环节。
0. 现在是制作视频的好时机吗？ 如果影片将涉及业务数据（利润、价格、客户、截止日期），在编写脚本前必须有一个这些数据的官方声明来源。如果有两个模型给出不同的数字，或者数字仍在讨论中，则不应制作视频：应告知用户，并提议打开电子表格进行讨论。制作一个视频需要两小时，并且会在观众脑海中固定一个数字。详见references/guion.md第9节。
1. 概念（与用户一起）。 决定模式（见上文）。首先阅读references/chispa.md：关于打破规则的格式、一个转折、提及真人的名字、一个回归的角色和一个“哇”时刻。明确目标观众、他们应感受到什么、视频时长以及将在何处展示。提出三个概念，每个用两三句话描述并附带文本预览，同时明确语气（已测试风格见references/guion.md）。如果用户已给出想法，请严格遵循：用户请求中的每个元素都应成为一个场景。
2. 验证将要断言的内容。 影片中关于产品的每一个陈述都应在产品代码中找到依据。代码中没有的，就不说；存在但被禁用的，就说出来并告知用户。这对于尚不存在的业务或项目同样适用：每个数字都应在GUION.md中注明其来源，并标记为事实、假设或提议。涉及承诺的词语（“保证”、“已存在”、“几秒内”、“符合法律”、价格）只有在已确定并写于某处时才能使用（references/guion.md第9节）。
3. 脚本。 在影片文件夹中创建GUION.md：包含用户的逐字请求、语音、音乐、以及一个时间表格（秒数、谁在说话、台词内容、画面内容）。台词要简短，每条语音一个音轨，使用中性西班牙语，不加长破折号。
4. 语音。 运行source scripts/llaves.sh和scripts/voces.py frases.json。使用Deepgram聆听生成的语音；对于质量不佳的，用--solo参数重新生成。如果旁白是用户的语音备忘录，则没有音轨文件：详见references/sonido.md第9和第10节。
5. 时间编排。 运行scripts/armar_narracion.py <inicios> --total <s>：在句子之间和画面独立叙事的段落留出空隙。使用Deepgram生成palabras.json（每个单词的时间戳）用于同步。
6. 音乐。 按场景划分音乐段落（scripts/musica.py）；使用scripts/pulso.py测量节奏和音量。如果段落位置不当，使用scripts/cortar_musica.py重新编排。
7. 混音。 使用包含的CC0音效库（sfx/）和合成音效（scripts/efectos_sinteticos.py），运行scripts/mezclar.py efectos.json，目标响度为-16 LUFS。检查： 使用oir_con_deepgram.py --comparar对比原始旁白和混音后的音轨：确保没有一个单词丢失。如有丢失，则降低该时间点的音效音量或为音乐让出空间。
8. 绘制。 对于商业广告，首先创建客户简报和固定故事板（assets/brief-cliente.md），并录制产品（references/promo.md）。复制对应风格的引擎（assets/motor-base.js漫画，assets/motor-suave.js柔和或assets/motor-promo.js商业广告）到mi-pelicula/pelicula.js，修改全局变量名称，根据时间表为每个场景编写一个函数。从assets/复制pelicula.html和hoja.html（修改.js和全局变量的名称；如使用其他字体则添加字体）。仅使用通用角色，不要使用真人形象。
9. 网格帧检查。 运行source scripts/preparar_render.sh和node $R/render.mjs pelicula.html fotos.png --stills ...，每张网格帧取9个时间点，覆盖整部影片。仔细检查，修正任何被遮挡、裁剪、过小、重叠或难以辨认的内容（常见错误列表见references/motor-visual.md），然后再次检查。对于商业广告，设置SEGURAS=1会绘制安全区，promo.md中包含“渲染前检查清单”。
10. 渲染。 在后台运行node $R/render.mjs pelicula.html <ruta>.mp4 30 1 6；将MP4复制到影片文件夹；运行scripts/liviano.sh生成轻量版用于消息发送。检查轻量版的一帧。如果风格变化较大，先渲染一个片段让用户查看动态效果（references/entrega.md第8节）。如果仅音频发生变化，则无需重新渲染：只需将新音轨与无声视频合并。
10.b 读取视频文本。 运行scripts/revisar_texto.sh <ruta>.mp4 "palabra1|palabra2"：对最终MP4进行每秒1帧的OCR检查，匹配产品中移除的词语（需要tesseract）。按钮上的文字会保存在影片文件中：如果产品的词汇发生变化，需要重新请求并重新录制（references/entrega.md第10节）。
11. 交付。 交付MP4，附带每个场景的摘要、已检查的项目以及用户决定。传单可以从同一影片生成（references/entrega.md第6和第7节）。如果用于演示文稿：准备data-peli幻灯片、控制器、字体、construir.py，并在浏览器中测试。
12. 保存。 将剧本、.js、页面、mp3和json音频文件提交到git（wav和mp4除外）；在文件夹的README中添加相关章节。
不可妥协的规则
- 真实性： 不得虚构产品信息或真人信息。敏感话题（如跌倒、健康）应严肃处理，并用诚实的细体文字说明。
- 密钥： 通过
llaves.sh从环境变量读取，绝不打印或写入文件。 - 不抄袭作品： 可以模仿著名电影的基调（“像《飞屋环游记》那样”、“超级英雄预告片”），但绝不使用其角色、场景、音乐或名称。
- 纯时间依赖：
seek(t)函数应无状态，不使用Math.random()（使用rng），不使用setTimeout。如果某一帧依赖前一帧，渲染结果将与实时显示不同。 - 一个视频固定一个数字： 没有官方来源的数字，就没有视频。每部影片都应在文件夹的README中记录其状态（草稿、已批准、谁看过、哪个版本）。如果在第三方查看后重新制作，需告知用户哪个数字发生了变化（
references/entrega.md第12节）。 - 测量，而非假设： “听起来不错”和“看着挺好”只有在经过Deepgram和网格帧检查之后才算数。
参考时间（一分钟影片）
剧本和语音：20分钟；时间编排、音乐和混音：20分钟；绘制：40-60分钟；网格帧检查和修正：20分钟；渲染和轻量版：5分钟；演示文稿和发布：15分钟。视觉修正是正常的：每部影片通常有5到10处修正。一个97秒的网页录制商业广告：渲染48秒，包括运动模糊共3分钟。如果修正发生在渲染之后，则需要重新渲染。
如果应用程序中途关闭
重要的内容已在影片文件夹中（音频、.js、剧本），渲染器可通过~/.cache/skill-motion-render中的preparar_render.sh自动重建。在每个长任务之前记录你进行到哪一步。