reel-captions-overlays

Reel 標題 + 疊加圖層

將已完成的 9:16 Reel（通常是 2160x3840 30fps，例如 talking-head-edit 的輸出）加入標題與疊加圖層。一切由一個 edit.json（標題頁面與疊加圖層，以影格為單位）驅動，兩個渲染器都讀取它，因此 HyperFrames 與 Remotion 版本會影格完全匹配。

SK=~/.claude/skills/reel-captions-overlays
PY=$($SK/scripts/find_python.sh)                          # faster-whisper large-v3 + opencv ($REELKIT_PYTHON, 程式碼庫 .venv, 或 python3)
AUDIO_PY=~/.cache/reel-audio/venv/bin/python               # 音樂階段 (scripts/setup_audio.sh 建立)
ANA_PY=~/.cache/reel-audio/analysis-venv/bin/python        # 參考風格分析 (scripts/setup_audio.sh --analysis)

預設工具：HyperFrames (Apache-2.0, 鎖定 [email protected])。Remotion (4.0.539) 保留作為一致性的建構。Remotion 對個人與 3 人以下的公司免費；較大的公司需要付費的公司授權才能商用 (remotion.pro/license)。HyperFrames 沒有此類授權條件。

工作流程

1. 設定（第一次執行） $SK/scripts/new_reel.sh <reel.mp4> <workdir> 此腳本會使用 large-v3 進行語音轉錄並產生逐字時間戳記、每 0.5 秒偵測臉部邊界框 (faces_src.json) 與鏡頭切換 (cuts.txt)，將 overlays.example.json 複製到 <workdir>/overlays.json，然後停止。
2. 填寫 overlays.json 先閱讀 words_raw.json。
   • corrections: 透過 token 序列修正品牌名稱，例如 ["Ackme"]→"Acme", ["re","-motion,"]→"Remotion,", ["Acme","Voice."]→"Acme Voice."。將品牌配對黏合為一個 token 可讓它們保持在一個標題頁面上。保留外語句子原樣（例如 "Même voix, autre langue."）。
   • sansWindows: B-roll 切換鏡頭、全螢幕覆蓋與 promptDemo 範圍的 [start,end] 秒數。該處的標題會切換為粗體無襯線字體（相同 75% 通道）。
   • overlays: 請參閱下方的風格規範與圖形計劃。時間以秒為單位，取自字詞時間戳。
   • sponsored: true: 用於付費或品牌 Reel。它會啟用展示節奏規則（下列贊助 Reel）與驗證警告。
3. 建構兩個專案 $SK/scripts/new_reel.sh <reel.mp4> <workdir> <workdir>/overlays.json
4. 渲染前預覽 cd <workdir>/hyperframes && npx [email protected] snapshot --at 2.5,20,30 --no-end (或在 remotion/ 目錄中執行 npx remotion still Reel x.png --frame=N --scale=0.5)。
5. 渲染 這些需要 Chrome，請在 Bash 沙箱外執行 (dangerouslyDisableSandbox)。在沙箱內，Chrome 會在 Mach-port 查詢時崩潰。
   • <workdir>/hyperframes/render.sh <out>_captions_hyperframes.mp4 會渲染一個 1080x1920 佈局，超採樣至 2160x3840，CRF 16 並啟用 faststart。
   • <workdir>/remotion/render.sh <out>_captions_remotion.mp4 會執行相同操作，使用 --scale=2、CRF 16、AAC 192k 與 faststart，然後執行 scripts/repair_remotion.py（請參閱注意事項）。
6. 驗證 $PY -I $SK/scripts/verify.py <reel.mp4> <out.mp4> <workdir>/edit.json <workdir>/faces_src.json <workdir>/qc <label> (如果影格、損壞影格、可讀性、卡片邊緣或 CTA 優惠失敗，則退出碼為 1 並顯示 FAIL；對於 60 秒的 4K Reel 約需 9 分鐘)
   • 檢查影格數與時長是否符合來源。
   • 掃描每個影格是否有損壞（錯誤的影片影格或黑色區塊）。corrupt_frames 必須為 0。
   • 抽查 5 個標題頁面：頁面開始前 1 個影格條帶必須為空，頁面開始後 2 個影格條帶必須填滿。
   • 測量每個疊加圖層下的臉部邊界框像素變化。這應該接近 0，除了全螢幕覆蓋與 promptDemo 卡片（它們刻意覆蓋臉部；這些會被排除在臉部、損壞影格與可讀性檢查之外）。
   • 列出 demo_beats (promptDemo 疊加圖層，或任何帶有 "demo": true 的疊加圖層)。當 edit.json 有 sponsored: true 且少於 2 個時，會列印 WARN 並將其加入 warnings（不是硬性失敗；修復 Reel 或在報告中說明原因）。
   • BEFORE/AFTER 分隔符 (v7, 警告) 對於每個 promptDemo before -> after 行配對，它會回報 before_after：兩個片段共有的字詞、剪輯中的間隙與渲染中測得的靜音、以及剪輯是否有切換條帶與切換音效 (build_edit ba)。重複字詞且沒有所有上述元素（間隙 >= 400 毫秒、條帶、音效）的配對會列印 WARN：沒有分隔符的重複行會被視為剪輯錯誤（請參閱 promptDemo）。
   • CTA 優惠 (v7, 硬性檢查) 帶有 offer 的 cta 必須完全可見 >= 2.5 秒，且高度 >= 40px（在 360px 手機上為 13+ px），並且實際繪製（其條帶中的像素變化）。<label>_offer_mobile.jpg 會以手機尺寸顯示；請查看它。贊助 Reel 的 CTA 如果沒有 offer 會得到 WARN。
   • 手機尺寸的可讀性 將 8 個標題頁面縮小至 360px 寬，然後測量筆畫粗細、文字高度與輪廓光暈（字型亮度減去周圍環狀區域）。下限：筆畫 >= 4.0px、高度 >= 28px、光暈 >= 130。legibility_ok 必須為 true。<label>_mobile.jpg 顯示裁切區域；請查看它。
   • 寫入一個聯絡表，包含每個疊加圖層中間的一個靜止畫面，以及一個同步裁切表。回報前請打開兩者查看。
7. 音樂 + 音效（預設階段；使用 --no-music 或 MUSIC=0 跳過） 填寫 <workdir>/music_plan.json（第一次執行時會從 music_plan.example.json 複製；它使用預設風格預設 steady-funk-bed；請參閱下方的音樂與音效設計），然後 $SK/scripts/music_stage.sh <out_hyperframes.mp4> <workdir> <out>_music.mp4 這會將背景音樂與音效混合在語音下，並以影片串流複製（不重新編碼）的方式將其混合到影像上，音訊修剪至影片長度，製作 <out>_music_mobile.mp4 手機版本（設定 MOBILE_OUT= 可將其放置於其他位置）並執行 music_verify.py，包括對照計劃的預設進行風格檢查。它必須顯示 PASS。它拒絕覆蓋現有輸出（使用 FORCE=1 允許）。它也會對任何句子失敗，如果其語音在音樂下低於 6 dB（報告中的 voice_over_music，--min-voice-over-music）：重要的是每一行是否都能清楚聽到。背景音樂是穩定的、未做閃避的節奏，大約比語音低 13 dB，因此即使段落平均通過，一個安靜的句子也可能沉入其中。請在上游修復失敗，使用 talking-head-edit 的語音電平調整或分段增益，而不是降低整個背景音樂。一個典型的通過訪談 Reel 測量結果為最小值 11.2 dB 與中位數 14.1 dB。 打開 <workdir>/qc/music_sections.png。第一次執行會建立 ~/.cache/reel-audio/venv (scripts/setup_audio.sh)。
8. 手機版本（用於發送，當跳過音樂階段時）：ffmpeg -i <out.mp4> -vf scale=720:1280:flags=lanczos -c:v libx264 -preset slow -crf 22 -maxrate 2800k -bufsize 5600k -pix_fmt yuv420p -c:a copy -movflags +faststart <out>_mobile.mp4（60 秒約 14-19 MB，低於 25 MB 限制）。複製母帶音訊，絕不重新編碼：第二次的 AAC 128k 編碼曾將一部 Reel 的真實峰值從 -1.3 提升到 -0.7 dBTP。

風格規範（來自參考 Reel）

以下所有尺寸皆位於 1080x1920 設計空間（以 2x 渲染）。共享 CSS 為 templates/style.css。

• 標題（v2：v1 標題是細白線條，在手機上難以閱讀。使用更粗、更大、有輪廓的版本作為預設值。）
  • 每頁一個字詞，偶爾兩個：短功能詞會與其鄰近詞結合，品牌配對會被黏合。
  • 文字大小寫與標點符號與口語一致（"content.", "Then"）。絕不大寫。沒有逐字高亮顯示：每頁 1-2 個字詞只會增加雜訊。
  • 字型：DM Serif Display（已捆綁，鎖定 @fontsource/[email protected]，OFL），大小 136px，白色。絕不再使用細襯線字型（例如 Instrument Serif regular）作為標題。Instrument Serif 保留用於紙張或紅色卡片標題。
  • 輪廓： 詞彙的描邊副本（::before 搭配 data-t，-webkit-text-stroke: 6px，因此字形外側 3px）使用 86% 的近似黑色，繪製在填充後面，因此絕不會使字母變細。陰影： 0 0 3px、0 5px 12px 與 0 14px 34px，皆為深色。
  • 適配： build_edit.py 會根據 templates/fonts/caption_metrics.json 為每個頁面設定 fs，使頁面絕不超過 820px（例如 "automatically." 為 127px）。如果字型更改，請使用 scripts/caption_metrics.py 重新產生度量。
  • 位置： 一條通道居中於 75% 的高度 (y=1440)，位於說話者的手與麥克風下方以及底部 20% UI 上方。只有在特寫鏡頭時會下降到下巴 + 6%（上限為 76%）。在典型的桌面設置中，手部位於 55-72%，因此 "下巴下" 通道 (60%) 會壓在手部上。
  • 動畫：一個 4 影格的彈出（縮放 0.86→1、y 14→0、淡入），提前一個影格開始，使詞彙在其第一個影格可見。
  • 頁面正好在詞彙的開始影格開始，並持續到下一個頁面，或者如果暫停則持續到詞彙結束 + 0.2 秒。
• B-roll 與全螢幕覆蓋標題： Inter 900，大小 120px，tracking -0.03em，相同輪廓與相同 75% 通道。
• 標題打孔卡 (titleCard，用於鉤子短語)
  • 一個磚紅色 #B23A2E 盒子，寬 810px (75%)，頂部位於 y=190。
  • 頂行：Anton 全大寫，大小 118px。其下方，一個白色 Instrument Serif 字幕，大小 62px。
  • 其底部約在畫面高度的 23%。這刻意比參考值高（頂邊 22-28%），因為臉部約從 26% 開始。
• CTA (cta)
  • 白色斜體襯線 "Comment" (82px)，上方有一個紅色盒子，內含 Anton 關鍵字 (196px，例如 "GUIDE")。與標題卡相同的上方帶狀區域。
  • 盒子在引導句子之後的 3 個影格彈出。
  • 優惠行 (offer，贊助 Reel，v7)：品牌優惠位於下巴下方的一張紙卡上，例如 "Use my link for a\nFREE 14-day trial."。使用品牌自己的措辭。\n 設定換行，全大寫詞彙（"FREE"）會獲得一個白底紅字盒子。"Comment / WORD" 仍然是主要元素；優惠是輔助行。build_edit.py 會推導出 offerF（來自 offerAt，預設為 CTA 開始 + 10 影格）、offerY（在 CTA 視窗內從 --faces 取得下巴 + 3%，保持在 55-60% 的高度，約在 1385px，高於標題墨水）與 offerFs（Inter 適配至 720px，最大 46px；低於 40px 時會發出警告）。卡片寬 780px (x 150-930，避開右側 UI) 並傾斜 -1.5°。
  • 優惠必須完全在畫面上 >= 2.5 秒。 如果 Reel 在說話者說出 CTA 後太快結束，請保持最後一個影格：$SK/scripts/hold_end.sh <reel.mp4> <frames> <reel_hold.mp4> 會串流複製剪輯，附加 N 個已編碼的最後一個影格副本與數位靜音，並檢查語音解碼是否樣本相同。選擇 N 使 Reel 正好在音樂節拍前結束（節拍 k = k * 60 / bpm，cue_at 為 0），將 CTA end 與音樂計劃區段 end 設定為新的長度，然後使用新的 --frames 執行 build_edit。背景音樂會在保持期間播放，並在最後一個影格處結束（例如：32 影格，結束於 68.2 秒，正好在 110 BPM 背景音樂的第 125 個節拍之前，68.207 秒；優惠完全顯示 3.2 秒）。
• 全螢幕覆蓋 (takeover，用於工具或產品提及，保持 1.5-3 秒)
  • 一個全影格深紅色 #8E1F17，帶有微妙的 8x14 淺紅色網格。
  • 一個白色圓角搜尋藥丸（左側放大鏡；右側麥克風與鏡頭），其粗體斜體查詢會在 14 個影格上打字輸入。
  • 其下方，一個白色圓角卡片，包含工具名稱（襯線 128px）、一行描述、一個紅色波形與 2-3 個晶片。
  • 絕不偽造真實產品 UI。 使用僅包含文字的 neutra 卡片。語音繼續在其下方進行。
• 浮動卡片 (floatCard，用於統計資料、提示或標籤；可選 kicker、width)
  • 一個紙張色 #FBF7F1 卡片，寬 470px，頂部位於 y=200，位於左側或右側。旋轉 ±3-4°，帶有深色陰影。
  • 內容為一個可選的 kicker + 大的 Anton 數字 + 襯線標籤 + 小型大寫行，或一個旗標變體：flag: "es"（kicker + CSS 旗標 + 字詞）或 flag: "us-es"（kicker "Same voice, different language" + 美國旗標 → 西班牙旗標 + 字詞）。
  • Emoji 旗標使用 CSS 繪製，因此它們絕不依賴 emoji 字型。
• 步驟清單 (steps)：頂部的一張紙卡 (y 150)，帶有紅色 kicker 與編號行 (DM Serif 54px)。每個項目都有自己的 at 時間，並在說話者說出時彈入；目前編號為紅色，較早的行變暗。在說話者說出 "three steps", "first... then" 時使用。
• 新舊對比 (split)：頂部並排的兩個傾斜窗格，深色 "Old way"（刪除線）與紅色 "New way"。新窗格