ultimate claude render

一个视频就是其状态随时间 t 变化的 HTML 页面。Claude 编写场景；引擎请求每一帧（window.__seek(t)），在无头 Chromium 中截屏，然后 ffmpeg 将其与语音、背景音乐和效果合成。没有“录制”环节：一切都是确定性和可重做的。

仓库包含引擎、音频脚本和此技能。每个人的视频存储在项目文件夹中，位于仓库外部。

在编写任何代码之前

运行 ucr doctor。 如果缺少 ffmpeg、Python（带 numpy/scipy）或 Chromium，它会提示确切的安装命令。
找到仓库。 此技能通过 ucr instalar-skill 安装，存放在克隆位置（ucr 在 PATH 中，或 node <repo>/bin/ucr.mjs）。如果找不到，请询问克隆位置；不要重新实现引擎。
生产前计划（视频重做成本高昂）：完整脚本、格式、品牌、可用媒体、有来源的数字、每句话出现的内容。用户分阶段审批：脚本 → 样式帧（ucr stills）→ 预览 → 最终渲染。未经脚本和帧审批，不得渲染完整视频。
优先使用现有品牌。 阅读用户的品牌手册、网站或应用，并编写 marca.json（颜色、字体、Logo）。切勿凭空捏造品牌身份或重新设计 Logo。客户素材若看起来像通用模板将被否决：必须使用真实的照片、颜色和 Logo。

流程

ucr novo meu-video --marca <品牌文件夹|_modelo|exemplo> --formato vertical
# 编辑 narracao.txt、projeto.json 和 cena.html
ucr tudo meu-video          # prep → midia → voz → tempos → batidas → sons → mix → render → QA

项目文件夹结构：

文件	说明
`projeto.json`	格式、帧率、品牌、语音、停顿、混音、渲染参数
`narracao.txt`	朗读的脚本；用于生成语音、字幕和场景时间
`cena.html`	场景文件（你编写的内容）
`marca/` 或其它路径的 `marca`	`marca.json` + 字体 + Logo
`midia/`	照片、视频、`trilha.mp3`、`sfx/<类型>/` 音效
`build/`、`.ucr/`、`saida/`	自动生成，无需版本控制

编写场景

骨架：请查看仓库中的 exemplos/modelo-cena.html。<script> 标签顺序很重要（GSAP → marca → projeto → tema → tempos → midia → batidas → motor）。完整 API 文档在 references/motor-api.md；摘要如下：

M.fundo()、M.camera()、M.marca()、M.legendas(F, { chaves: [...] })、M.grande(texto, { t, fim })
M.celular(pai, {x,y,B})、M.janela(pai, {...})、M.terminal(pai, {linhas})、M.cursor/clicar/tocar
M.foto(pai, 'nome', {...})、M.video(pai, 'nome', { som: true })（从 midia/ 获取，需先执行 ucr midia）
M.T('单词') = 这些单词被说出时的时刻。将所有动画锚定在语音上，而非固定秒数：修改脚本中的一句话不会打乱其余场景。
M.som(t, 'tipo') 标记混音中的音效；M.batida(t) 将剪辑对齐到背景音乐节拍。

场景黄金规则：

一切仅依赖 t。 时间线动画（M.tl）、计数器和绘图使用 M.ATUALIZAR.push(t => ...)。禁止 setInterval、Date.now()、带 play() 的 <video> 或 CSS 动画。
平台安全区域： QA 会检测超出安全区域的文本（竖屏：顶部 14%，底部 25%）。
停顿导致流失。 任何内容静止超过约 1.5 秒都会导致观众流失（QA 会测量）。M.camera() 可为场景添加 3D 微动；深色背景上的暗色卡片如果不添加边框和亮度，移动时不易察觉。
每句话改变画面。 新句子对应新图像或新运动。
渲染前： 在 3 或 4 个时刻运行 ucr stills。任何脚本错误（重复变量、单词不在旁白中）都会立即显示页面错误消息。

音频

语音： projeto.json → voz.provedor：edge（免费，无需密钥；适合测试，不可商用）、elevenlabs、fal 或 arquivo（你录音；使用 Deepgram nova-3 获取时间戳）。屏幕文本来自 narracao.txt，时间戳由语音决定。
呼吸/停顿： "respiros": {"2": 1.2} = 索引为 2 的句子后插入 1.2 秒静音（用于留出图像进入时间）。
背景音乐： midia/trilha.mp3（需要商业许可！）或 "sintetica"（原创，无需许可）。音乐会自动降低音量以衬托语音（ducking）。
音效： 合成音效（whoosh、冲击、点击、闪烁、上升、快门、弹出、按键、低音、纸张）或 midia/sfx/<类型>/ 中的文件。
母带处理： −14 LUFS 和 −1.5 dBTP（符合 Reels/TikTok/Shorts 标准），最终文件会自动测量。

详细信息和注意事项：references/audio.md。

QA 和交付

渲染过程自动运行 QA（输出 saida/<名称> - QA.txt）：检查尺寸、颜色（BT.709 标记）、静止帧、黑场片段、响度、峰值和安全区域外的文本。QA 通过不代表批准：请打开 MP4 查看帧内容并监听。报告 QA 检测到的问题和你发现的异常；未经查看切勿宣布“完成”。

输出文件：saida/<名称>.mp4（交付版，22 Mb/s）和 saida/<名称> - leve.mp4（30 fps，用于消息发送）。

遇到问题时的处理方法

场景未就绪（A cena não ficou pronta）：脚本错误（页面错误消息会立即显示），或没有任何错误但 <script>/媒体路径错误（此时会等待 90 秒超时）。
渲染慢：请查看 references/armadilhas.md（滤镜模糊、背景滤镜、全屏混合、页面中的 <video>）。
仅重新渲染部分内容：ucr render <文件夹> --de 30 --ate 38（若参数相同，将复用之前渲染的片段）。
长渲染前检查磁盘空间：df -h（45 秒 1080×1920 视频约需 250 MB 临时片段和约 145 MB 最终输出）。

参考资料（按需阅读）

references/motor-api.md：完整 M.* API 及示例
references/marca.md：marca.json 字段详解、格式和安全区域
references/audio.md：语音、停顿、背景音乐、音效、混音、许可证
references/receitas.md：照片、嵌入式视频、真实屏幕、终端、横屏、变体、调色板切换
references/armadilhas.md：已知问题（实测）按主题分类

ultimate-claude-render