talking-head-recut

Talking Head Recut

Talking Head Recut 針對能夠完整播放的本地影片，依據演講/對談內容的時間軸，在其上疊加一系列經過設計且定時出現的視覺圖卡——包括標題、下三分之一圖卡（Lower-Thirds）、數據強調、引用金句、側邊欄、子母畫面（Picture-in-Picture）。Agent 會直接在對話中設計圖卡（包含時間點與內容）並手寫每張圖卡的 HTML 程式碼，隨後組裝成單一的 HTML 組合，並透過 hyperframes 將其渲染導出為 MP4。本流程沒有固定的原型列表或預設圖卡結構——所有覆疊圖卡完全依據逐字稿的實際內容量身定制。

開始製作前，請先確認路線。 本 Skill 適用於對現有的口播/訪談影片片段進行視覺圖卡包裝（如標題、下三分之一圖卡/lower-thirds、數據強調、引用金句、側邊圖卡、子母畫面）。如果使用者想要的是純字幕（將口播語音轉為文字字幕）→ 請使用 /embedded-captions；如果只需要單一簡短無配音元件（例如單一 Logo 片頭/下三分之一壓條）→ 請使用 /motion-graphics。原始影片片段會保持原樣播放——對影片進行重新剪輯、調色、裁切、調整順序或調整音訊屬於 NLE 剪輯範疇，不在本 Skill 範圍內。如果需要從 URL / 主題 / PR 從頭生成影片 → 請使用影片創作工作流（Creation Workflows）。若不確定該選圖卡包裝還是純字幕？請先閱讀 /hyperframes。

embedded-captions 的視覺包裝姊妹篇。 字幕是把口播語音呈現為可讀的下方字幕；而本 Skill 是在播放的影片上方疊加設計好的視覺圖卡。純字幕 → embedded-captions。從頭製作影片 → 影片創作工作流（product-launch-video / faceless-explainer / …）。

工作目錄中可供檢視的中間檔案：

• metadata.json — 影片時長（duration）/ 寬度（width）/ 高度（height）/ 影格率（fps）
• audio.mp3 — 抽出的音訊
• transcript.json — 扁平的單字陣列 [{ text, start, end }, …]（Whisper 格式；無 segments，無 words 包裹層）
• storyboard.json — 輕量級圖卡大綱（Agent 的規劃藍圖）
• public/cards/card-XX.html — 每張圖卡獨立的 HTML 碎片
• public/index.html — 最終組裝完成的組合文件
• output.mp4 — 渲染完成的影片

CLI 路線解析

# hyperframes — 語音轉寫（本地 Whisper）+ 將組裝好的 HTML 渲染為 MP4
npx hyperframes --help

本 Skill 完全基於 hyperframes CLI 以及系統的 ffmpeg / ffprobe 運作。
語音轉寫使用的是本地 Whisper（透過 hyperframes transcribe），不需要第三方服務、API Key，也不會遇到限流問題。

工作流程

1. 檢查環境

npx hyperframes doctor          # 檢查 ffmpeg、Headless 瀏覽器及渲染依賴
# 確認內建資源：
ls "<SKILL_DIR>/assets/fonts" "<SKILL_DIR>/assets/vendor/gsap.min.js"

必要條件：

• ffmpeg / ffprobe（系統環境）
• <SKILL_DIR>/assets/fonts/*.woff2, <SKILL_DIR>/assets/vendor/gsap.min.js（打包在本 Skill 內部，將在步驟 9 複製到工作目錄）

語音轉寫無需金鑰——hyperframes transcribe 會在本地執行 Whisper（步驟 4）。

在 macOS 上強烈建議使用以下設定來執行 hyperframes render：

export PRODUCER_BROWSER_GPU_MODE=hardware

2. 建立工作目錄

所有產出物皆存放於 videos/<project-name>/ 下——此為所有影片工作流（product-launch-video / faceless-explainer / pr-to-video）的統一規範。請保持工作區根目錄為當前的執行目錄（cwd），所有產出的檔案都會寫入在此子目錄下。

VIDEO_PATH="/absolute/path/input.mp4"
WORK_DIR="videos/$(basename "$VIDEO_PATH" | sed 's/\.[^.]*$//')"
mkdir -p "$WORK_DIR"

3. 提取音訊與元資料

# 元資料 — 時長 / 寬度 / 高度 / fps
ffprobe -v error -select_streams v:0 \
  -show_entries stream=width,height,r_frame_rate \
  -show_entries format=duration -of json "$VIDEO_PATH" > "$WORK_DIR/metadata.json"
# 音訊
ffmpeg -y -i "$VIDEO_PATH" -vn -acodec libmp3lame -q:a 2 "$WORK_DIR/audio.mp3"

產出：metadata.json（讀取 width/height/duration；fps 為計算後的 r_frame_rate 分數值，例如 30000/1001 → 29.97）+ audio.mp3。

4. 語音轉寫

npx hyperframes transcribe "$WORK_DIR/audio.mp3" -d "$WORK_DIR" --json --model small.en

本地 Whisper — 無需 API 金鑰、無代理伺服器、不受速率限制。會在工作目錄寫入單字層級的 transcript.json（包含單字 text + start / end 時間戳記）。
在步驟 6 中讀取此檔案以獲取驅動圖卡時間軸的單字/句子時間點；如果需要段落層級的區塊，請根據標點符號或停頓自行將單字組合成分句。

限制在媒體總時長內。 Whisper 返回的最後一個單字的 end 時間可能會稍微超出影片實際長度——請務必將每張圖卡的 endSec 與 composition.durationSeconds 截斷/限制在 metadata.json 的總時長內，否則渲染結果結尾會出現一段黑畫面。

5. 修正逐字稿

transcript.json 是一個扁平的單字物件陣列 — [{ "text": "...", "start": s, "end": s }, …]（沒有 segments 陣列，沒有 words 包裹層；每個單字的 key 為 text）。請讀取並修正明顯的 ASR（自動語音辨識）錯誤：

• 同音異字、產品名稱、專業術語、標點符號
• 原地修改單字的 text；保留其 start / end 時間戳記
• 沒有預先分組好的 segments 陣列 — 當你需要段落層級的區塊來進行圖卡時間規劃時，請自行將單字組合成分句（在句末標點或停頓處進行切分）

6. 草擬輕量級分鏡腳本（在對話中進行）

不涉及任何 CLI 機器指令。 讀取 transcript.json + metadata.json 並直接設計圖卡。storyboard.json 是 Agent 內部的規劃藍圖——沒有 CLI 命令會直接讀取它；它的存在是為了讓你在撰寫每張圖卡的 HTML 之前，能夠清晰思考時間軸與內容。請保持格式與下例一致，以便此大綱能在步驟 9 中驅動組合文件的撰寫：

{
  "schemaVersion": 3,
  "composition": {
    "fps": 30,
    "width": 1080,
    "height": 1920,
    "durationSeconds": 121.2,
    "layout": "portrait",
    "themeId": "noir",
    "seed": 42
  },
  "videoTrack": {
    "sourcePath": "input-video.mp4",
    "startSec": 0,
    "endSec": 121.2,
    "bounds": { "x": 0, "y": 0, "width": 1080, "height": 1920 }
  },
  "subtitles": { "enabled": false },
  "cards": [
    {
      "id": "card-01",
      "intent": "Hook with the speaker's anxious midnight question",
      "startSec": 0.5,
      "endSec": 13.0,
      "accentIndex": 0,
      "zone": "fullscreen",
      "contentHints": {
        "kicker": "AN HONEST QUESTION",
        "title": "The soul-searching question at 11 PM",
        "detail": "Client's 60-second voice message: 'If the RMB appreciates, does that mean my USD policy is a terrible loss?'"
      }
    }
  ]
}

必要的 Card 欄位：

欄位	型態	用途
id	string	用在圖卡 HTML 與 GSAP 選擇器中的固定 ID
intent	string	自然語言描述；提供給圖卡合成使用
startSec / endSec	number	以秒為單位的時間（endSec > startSec）
accentIndex	0 | 1 | 2 | 3 | 4	指定此圖卡套用 5 種主題強調色中的哪一種
zone	enum（見下方）	圖卡在畫布上的展示區域
contentHints	object	自由包容物件；Agent 在此放置前導標題（kicker）、主標題（title）、細節（detail）、數據（data）、引用（quote）
archetype（選填）	string	自由標註的標籤，用來標記圖卡模式；未指定 = 自由形式（預設）
transition（選填）	enum: cut | fade | slide | wipe	聲明式的圖卡間切換過渡

五種 zone 區域值：

zone 區域	解析後的邊界 (bounds)	使用時機
fullscreen	覆蓋整個畫布	重點高光時刻、大數字、核心金句
whiteboard-area	內縮 40px 邊距（或直式高度的 45%）	密集數據 / 帶有標註的內容
lower-third	底部 30% 區域壓條	在可見影片上方呈現標註說明
side-panel	右側 42%（橫式）或底部 40%（直式）	一側放置數據，另一側保留影片
video-overlay	全畫布，主要預留給半透明圖卡	在全螢幕影片上方顯示浮雕覆疊標註

在步驟 9 組裝組合檔案時，請按照上表將每張圖卡的 zone 解析為圖卡容器 wrapper 上的像素邊界。
影片邊界在組合層級（videoTrack.bounds）設定一次；若要使影片看起來像是在「不同圖卡間移動」，請在組合檔案的 <script> 中針對 #video-wrap 撰寫 GSAP 補間動畫（tweens）（詳見步驟 9）。

沒有預設的圖卡角色，沒有預設的敘事架構。 圖卡的形式完全由影片實際講的內容決定——可以是全金句引用，也可以是全數據展示；可以以數字開場，也可以以故事開場。讓逐字稿本身決定節奏。

要分出多少個精髓要點？——由「時長 + 資訊密度」自動推導。 沒有固定上限。根據影片時長設定基礎節奏，再根據資訊密度進行微調。僅設固定下限：最少 5 張圖卡，以確保短影片也能保有節奏感。

步驟 1 — 依據時長設定基礎節奏（中等密度下的自然「秒數/每張圖卡」）：

影片時長	基礎節奏（每張圖卡的秒數）	說明
< 60秒（短影片/Reel）	6–8秒	短影片觀眾期待快速剪輯與切換
60秒 – 3分鐘	8–12秒	一般社群影片節奏
3 – 10分鐘	12–20秒	留出呼吸空間；每張圖卡承載更多內容
10 – 30分鐘	20–35秒	長影片講座 / 訪談的自然節奏
> 30分鐘	30–60秒	單元劇、分章節般段落感

步驟 2 — 密度乘數（縮放基礎節奏）：

逐字稿中的特徵訊號	乘數	效果
高密度 — 很多數字、明確的主張、斷奏快節奏、清單式枚舉、每 1–2 句話就是一個新觀點	× 0.7	剪輯更密集