Criativos AgroPerforma · Fábrica Blindada
基于HyperFrames构建的竖版创意视频编辑流水线（Reels/广告）。
每个创意变成一个项目，通过JSON配方文件(creative.base.json)定义，
并由template.html渲染成最终视频。
客户详细规则、决策和反馈历史记录：
references/regras-do-cliente.md。 编辑前请务必阅读——这些规则优先于本文档的任何标准。
强制流程（3次审批）
- 剪辑 → 轻量1080p预览（
cut.py --preview）+ 建议名称（代码+昵称，例如AP-08 · Tudo Depende de Você）。用户批准。 - 草稿 → 动态/字幕的关键帧（
hyperframes snapshot），非完整视频。如需改变动态（如缩放），请使用render -q draft发送预览。 - 执行 → 4K剪辑（不带
--preview的cut.py）+render4k.sh（4K 24 fps）+barscan.sh（黑边检测）。
一次只处理一个视频，从头到尾。 Whisper large-v3 + ffmpeg 4K + 并行渲染会导致MacBook过热重启。
环境
- 客户SSD为exFAT格式（无软链接 →
hyperframes init失败）。请在APFS卷的磁盘镜像上工作，挂载至/Volumes/AGROPERFORMA-HF（scripts/montar.sh）。所有脚本假定此路径：projetos/<código>/、projetos/_kit/（即此文件夹scripts/+assets/）、_scratch/（临时文件，如faces.swift、shift.swift）。 - 每个命令都需要
source scripts/env.sh：TMPDIR、历史和HyperFrames缓存均位于卷上，绝不占用Mac磁盘空间。 - 卷在应用重启时会自动卸载——每次执行步骤前需重新挂载；长任务使用
nohup caffeinate -i。 - 字体：Helvetica Now Display Bold（已获得许可——不在仓库中；请复制到
projetos/_kit/fonts/）。
第1步 — 剪辑
| 步骤 | 工具 |
|---|---|
| 语音通道（左右声道不同麦克风；取最强通道，在方向出现时确认谁在说话） | prep_lote.sh（电平 + 转录） |
| 逐句转录原始素材中的句子（Whisper长停顿不准确） | phrasemap.py <wav> |
| 去除>0.2秒的停顿，保留0.07秒呼吸间隙 | plan.py <wav> a:b … --gap 0.2 --pad 0.07 |
| 口误（如“da, do”、“tem em, um, uma”、“cli… clica”）：RMS 20ms + 合并候选片段并转录合并结果；通过分离音节确认 | fine.sh、chunk.sh |
连续剪辑，与画面对齐（单个<video> → LUT永不“分段”），两侧均使用选定通道，0.5秒淡出 + 0.7秒黑屏 | cut.py [--preview] [--no-fade] [--multi] |
从实际说话开始处开始；在最后一个词后约0.5秒淡出结束（例外：如果人物在结尾移开目光 → 使用--no-fade）。
第2步 — 配方（creative.base.json）
{
"theme": "green", // green = AgroPerforma (#62AE46) · blue = Fábrica Blindada (#1f4cd7/#0c1f51)
"adjust": {"highlights": -0.25, "shadows": -0.15}, // 或 "exposure": 0.15
"trackMode": "shot", // 每次缩放片段时居中人脸一次
"cam": [{"start": 0, "end": 6.78, "s": 1.12, "to": 1.04, "cx": 0.5}],
"captions": [["静态文本", 1.12, 2.48]],
"motions": [{"start": 5.45, "end": 6.78, "top": 900,
"items": [{"text": "Tudo depende de você?", "at": 5.45, "kind": "secondary", "check": true, "ring": 5.8}],
"arrow": 6.2}]
}
analyze.sh <projeto>→ 逐帧检测人脸（Apple Vision）+ 剪辑转录；caps.py自动生成字幕（每2-4个单词分组，修正“Eo/Ea/Eaí”，合并孤立词）。mkcfg.py <projeto>→ 完成缩放/跟踪并通过build.py生成index.html。- 字幕静止在画面中间，当有动态元素在屏幕上时消失。
- 类型：短（CTA约10-15秒）仅动态 · 中等字幕+关键词动态 ·
-GRANDE仅字幕+最后CTA动态。 - 温和缩放： 40秒内约5个片段，每次缩放间隔≥6秒，仅在思维转换处使用；交替拉近/拉远。每个片段居中人脸，逐帧限制在缩放边界内（绝不显示边缘）。
第3步 — 执行
python3 scripts/cut.py "<bruto>.MP4" media/cut.mp4 L <a:b> … # 4K
python3 scripts/mkcfg.py projetos/<código>
HF_DEST="<pasta EDICAO>" scripts/render4k.sh <código> <Nome>_v1_4K
scripts/barscan.sh "<pasta EDICAO>/<Nome>_v1_4K.mp4" # 检查是否出现黑边
将所有信息记录在该项目的PROJETO.md（原始素材、通道、文本、输出内容、版本）和projetos/CATALOGO.md中。版本需编号，切勿覆盖。
示例
examples/目录包含真实配方（creative.*.json）、PROJETO.*.md、钩子变体生成器（ap08_variants.py——相同主体，三种开头句式）和渲染队列（fila_*.sh）。