morrimoz/talking-head-clip-review

談話頭影片片段審查

將原始的 talking-head 影片素材轉換為已核准的精選片段，無需任何人手動拖曳時間軸。代理會進行轉錄、對齊與建議。使用者只需在一個頁面上進行核准。然後代理會根據核准的內容進行組裝。

轉錄資料保留在本機。原始影片絕不會被修改。

嚴格規則

• 絕不修改、移動或重新匯出原始影片。所有處理僅基於 in/out 點與衍生檔案。
• 絕不刪除使用者的素材或清空垃圾桶。如果磁碟空間不足，請告知使用者並讓他們自行處理。
• 在暫存資料夾中工作。只有預覽影片、海報、審查頁面與精選片段會放置在媒體檔案旁。
• 不要自行發明文字。片段文字來自轉錄稿。選擇性的片語修正需透過 --fix 傳遞一個 JSON 映射（請參考 references/term-corrections.example.json）。不要套用範例檔案。
• 在挑選片段前，請核對鏡頭前說出的事實（時間、數字、「10 分鐘前」等）與真實錄影。
• 保留的片段中不得有看監視器、碰撞麥克風、點擊聲或呼吸噪音。每次重新編輯後（不僅是第一次精選時），都要重新執行視線偵測（步驟 5）並聆聽每個編輯點。若有噪音，請將其靜音或剪掉，而不是剪掉旁邊的字詞。
• 補錄與重新錄製的台詞必須與主要拍攝的語氣、音量與空間感一致（相同麥克風、增益、距離、EQ 與降噪）。如果某句台詞聽起來會模糊或有盒子感，請標記出來，而不是將其輸出。
• 在為使用者撰寫的任何內容中使用連字號 (-)，而非 em dash (—)。
• 單字邊界是硬限制，即使提示要求緊密剪裁或視線修剪也是如此。片段在 Whisper 的單字時間前後會分別加上 0.15 秒的預捲與 0.25 秒的尾端（Whisper 的單字邊界經常偏早或偏晚），並確保不會與相鄰單字重疊。暫停與視線修剪僅允許在單字之間的間隙內進行，並在每個單字旁保留至少 0.1 秒。如果視線偏移與口語單字重疊，請保留該單字並標記（away_words，在串接影片中以紅色邊框顯示），絕不裁剪。使用 build_review.py --gaze-trim 進行邊緣修剪，不要自行編寫修剪腳本。手動設定的 exact_spans 也會被推回到單字邊界。

設定（每台機器執行一次）

執行 scripts/check_deps.sh。它需要 ffmpeg、ffprobe、python3 與一個 Whisper 後端。Swift 是視線偵測步驟的選用項目。安裝步驟：references/setup.md

目錄結構

WORK/                      暫存資料夾，例如 ./talk/
  tx/<take>.wav|json|txt   16 kHz 單聲道音訊、含單字時間戳的 Whisper JSON、可讀的轉錄稿
  picks.json               節拍 + 候選片段（代理編輯此檔案）
  picks_resolved.json      逐字精確的範圍、文字、時長（自動產生）
  pose.json                視線偏移區間（macOS 選用）
REVIEW/                    放置在媒體檔案旁，例如 ./review/
  previews/<take>.mp4      用於頁面的 540p H.264 副本
  posters/<beat>-<i>.jpg
  "<Title> - take review.html"
  "<Title> - picks stringout (540p).mp4"
SELECTS/                   selects.json, selects.csv, selects.edl, selects.mp4

以作品名稱命名集數，例如 launch-01。保持拍攝代碼簡短（A、B、C），並在 picks.json 中將其對應到檔案名稱。

步驟

1. 盤點。 使用 ffprobe 檢查每個拍攝素材（時長、大小、fps、旋轉角度）。手機素材常是可變影格率與垂直方向。預覽與渲染會將其標準化。詢問哪些是已調色的匯出檔（需要剪輯），哪些是原始相機檔案（應忽略）。
2. 轉錄。 執行 python3 scripts/transcribe.py --out WORK/tx TAKE...。如果 Whisper 套件不在預設的 python3 上，請使用 check_deps.sh 報告的直譯器。如果檔案仍在匯出中，請在背景使用 --watch FOLDER --expect N：它會等待直到每個檔案停止增長至少 30 秒。Apple Silicon 上的首選模型：mlx-community/whisper-large-v3-turbo，含單字時間戳，並關閉 condition_on_previous_text。當語音非英語時需設定 --lang。
3. 草擬精選。
   • 模式 (a)，單一腳本的多個拍攝：撰寫 WORK/script.txt，每行一個句子或談話點（如需 ID 可寫 id | name | text）。執行 python3 scripts/segment.py takes --tx WORK/tx --script WORK/script.txt --out WORK/picks.json A=take-a B=take-b ...。它會找出每個拍攝中對應每個句子的每次嘗試（基於模糊詞彙比對，因此重錄會顯示為分開的候選項），並自動勾選最流暢的一個。
   • 模式 (b)，單個長錄影：python3 scripts/segment.py single --tx WORK/tx --out WORK/picks.json A=long-take 會在停頓超過 1.2 秒與句子結尾處裁剪，生成 4-40 秒的片段。
   • 然後自行閱讀 .txt 轉錄稿。修正 in/out 點，為重錄與瑕疵加入 cut: [[a,b]]，合併或分割節拍，並為每個候選項撰寫真實的 why（清晰、重錄、講錯詞、與螢幕錄影相符）。優先選擇與對應螢幕錄影一起拍攝的素材。自動評分僅用於打破平手。
4. 建構頁面。 python3 scripts/build_review.py --work WORK --media SRC --out REVIEW --title "launch-01" --stringout。段落會在字詞間隔超過 0.6 秒處分割，並使用 silencedetect -35dB / 0.35s 縮緊。在候選項中加入 keep_pauses: true 以跳過此步驟。填補標記：--pre 0.15 --tail 0.25 --guard 0.1。僅當您有真實的片語映射時才傳遞 --fix path/to/corrections.json。在瀏覽器中開啟 HTML。影片在點擊時載入，因此頁面開啟很快。
5. 選用，macOS：視線偵測。 python3 scripts/gaze.py --work WORK --review REVIEW，然後以 --stringout --gaze-trim 重新執行步驟 4。視線偏移的影格在串接影片中會以紅色邊框顯示。稍後以螢幕素材覆蓋它們並保留音訊。
6. 人工審查。 告知使用者要執行的操作：播放、使用/跳過、備註，然後「儲存決策 (JSON)」。它會下載 <slug>-decisions.json。「複製為文字」是備用方案。未修改的卡片會保留建議。
7. 套用備註。 讀取決策 JSON。將每個備註轉換為 picks.json 的編輯：cut、in/out、audio_only: true、grade: "eq=gamma=1.28:brightness=0.03"、optional: true。先備份一次（cp picks.json picks.before-notes.json）。重新執行步驟 4，並摘要每個備註與您所做的變更。
8. 組裝。 python3 scripts/assemble.py --work WORK --media SRC --decisions /path/to/<slug>-decisions.json --out SELECTS --render。您將獲得一個影格精確的全解析度 selects.mp4、一個 CMX3600 selects.edl（可匯入 Premiere、Resolve、Final Cut）、selects.csv 與 selects.json（含視線偏移範圍與備註）。
9. 驗證。 聆聽每個編輯點（無剪斷的首或末音節、無視線偏移、無噪音）。使用 ffprobe 比對渲染時長與 selects.json 中的總和，並製作縮圖索引：ffmpeg -i selects.mp4 -vf "fps=1/6,scale=180:-1,tile=10x3" -frames:v 1 sheet.jpg。檢視它，然後報告長度、變更內容以及仍需使用者處理的事項。

picks.json 格式範例

{"episode":"launch-01","mode":"takes","takes":{"A":"take-a","B":"take-b"},
 "beats":[{"id":"01a","name":"Hook","script":"...","cands":[
   {"take":"B","in":0.82,"out":21.2,"pick":true,"why":"清晰，與螢幕相符。","cut":[[51.4,53.82]],
    "note":"","audio_only":false,"grade":null,"optional":false,"signals":{"dur":20.1,"wpm":162,"fillers":0,"repeats":0}}]}]}

提示

• 隨時使用轉錄 JSON 抽查任何單字的時間。圍繞某個備註的 word@start-end 轉儲是放置剪裁點最快的方式。
• 如果 ffmpeg 沒有 drawtext，請使用 drawbox 或 hue 來標記影格，而非文字。
• 大型渲染：先檢查可用磁碟空間。4K 素材的空間需求會快速增加。