創意廣告 AgroPerforma · Fábrica Blindada
基於 HyperFrames 構建的直式創意廣告（Reels/Ads）編輯管道
(npx hyperframes …)。每個創意廣告變為一個專案，包含一個 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會失敗）。請在掛載於/Volumes/AGROPERFORMA-HF的 APFS 磁碟區映像檔上工作（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 — 剪輯
| 步驟 | 工具 |
|---|---|
| 語音軌道（L 和 R 為不同麥克風；選擇較強者，確認方向出現時誰在說話） | 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 20 毫秒 + 合併候選區段並轉錄合併結果；隔離音節以確認 | 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" # 0 個畫格有黑邊
將所有內容記錄在專案的 PROJETO.md 中（原始素材、軌道、文字、輸出內容、版本）以及 projetos/CATALOGO.md 中。版本須編號，絕不可覆寫。
範例
examples/ 包含實際配方 (creative.*.json)、PROJETO.*.md、鉤子變體產生器 (ap08_variants.py — 相同主體，三個開場句子）以及渲染佇列 (fila_*.sh)。