Video Research

---
name: video-research
description: 本機影片研究員。丟一條 Bilibili、YouTube（含 Shorts）、Facebook Reels、Instagram、TikTok 或任何 yt-dlp 支援的影片連結，在自己電腦上把影片變成「元資料＋逐字稿或字幕＋縮圖總表」素材包，再由 Claude 寫出標明證據來源的分析報告。不用 API 金鑰、不上傳影片、零成本。只要使用者貼影片連結並想知道「這支在講什麼」「幫我分析這支」「整理重點」「這個 UP 主說了什麼」「看看這支業配」「幫我看這個 Reel／Short」，即使沒說「分析」兩個字也要用本 skill。相依（yt-dlp、ffmpeg、faster-whisper）會自動安裝。不適用：從文字生成影片（ai-teaching-video）、剪輯既有素材（video-use）、下載後不分析只存檔。
---

# Video Research：本機影片研究員

> **v1.0｜2026-10-03**：首版。從四支實跑（FB Reel 口說業配、YouTube Shorts 有字幕動畫、B 站無聲字卡電影、B 站口播解說）抽出的工作流、判讀規則與報告格式。

## 這支 skill 做什麼

把「AI 看影片」拆成兩段：**腳本負責收集證據，Claude 負責分析**。腳本把影片變成文字和圖片，Claude 讀完寫報告。這樣不需要任何雲端影片模型，長片也不會撞 token 上限，影片不離開電腦。

## 能力邊界（先講清楚，別硬做）

做得到：
- 任何 yt-dlp 支援的網站（上千個），不登入能抓的影片。
- 口說內容：有平台字幕用字幕，沒有就本機 Whisper 轉錄。
- 畫面內容：抽幀與縮圖總表，Claude 直接讀圖，大字卡、UI、數字都讀得到。
- 元資料：標題、作者、觀看、讚、文案、標籤，各平台給多少抓多少。

做不到（界外）：
- 聽聲音以外的音訊細節（語氣、音樂風格）。Claude 聽不到聲音，只能靠轉錄文字。
- 畫面與聲音的毫秒級同步（例如「說到『按這裡』時滑鼠點了哪」）。要這種精度請切片段交給 Gemini 之類的原生影片模型。
- 要登入才看得到的影片與完整留言。腳本**不會自動碰使用者的瀏覽器登入狀態**，需要時由使用者明示後加 `--cookies chrome`。
- 驗證影片的宣稱。報告只標「影片說了什麼、畫面顯示什麼」，不確定的一律標「（需查證）」，絕不編造。

降級階梯（缺料不留空洞，每一級都在 brief.md 明講）：
1. 全套：元資料＋字幕或轉錄＋截圖＋縮圖總表。
2. 沒 Whisper 可用：元資料＋平台字幕（若有）＋截圖。口說層標「不可用」。
3. 沒 ffmpeg：元資料＋平台字幕（若有）。畫面層標「不可用」。
4. 沒 yt-dlp 且裝不起來：停止並給手動安裝指令。沒有它什麼都抓不到。

## 對焦閘門（問得少、問得準）

使用者貼了連結，**直接跑**，不要先問一堆。只有兩種情況停下來問：
- 連結要登入才看得到（yt-dlp 報錯）：問是否同意借用瀏覽器 Cookie，說明這會讀取登入狀態。
- 使用者明顯有特定目的（寫講義、做競品比較、抓金句）但沒說清楚格式：一句話確認交付物，再跑。

能從語意判斷的不問。例如「這支業配在推什麼」就是要可信度判讀，「幫我整理重點」就是要摘要為主。

## 工作流（四步）

### 步驟 0：環境準備（透明，不要求使用者動手）

第一次跑時 `scripts/bootstrap.py` 會自動檢查並安裝 yt-dlp、ffmpeg、faster-whisper，裝過就秒過。要單獨看狀態：

```
python <skill 路徑>/scripts/grab_video.py --doctor
```

### 步驟 1：跑腳本，拿到素材包

```
python <skill 路徑>/scripts/grab_video.py <影片連結>
```

產出在目前工作目錄的 `work/<平台>_<影片ID>/`：

| 檔案 | 用途 |
|------|------|
| brief.md | 交接單。元資料、文案、逐字稿或字幕、降級提示。**先讀這個** |
| sheets/ | 縮圖總表，每格左上角有時間碼。**再讀這個**，一次看完全片 |
| frames/ | 單張截圖，短片每 2 秒、長片每 8 秒一張。需要看清楚某一幕時用 |
| transcript.txt | 純逐字稿 |
| info.json | yt-dlp 原始元資料 |
| video.mp4、audio.wav | 原始檔。分析完可刪 |

常用選項：`--cookies chrome`（要登入的影片，須使用者同意）、`--model medium`（專有名詞多時換大一點的 Whisper）、`--lang zh`（指定語言）、`--interval 1`（字卡密集的短片抽密一點）。

腳本會依長度自動決定抽幀密度與縮圖總表格距，通常不用手動調。

### 步驟 2：讀證據，兩層互相校正

讀 brief.md 和 sheets/ 全部縮圖總表。**逐字稿負責「講了什麼」，截圖負責「名字和數字」**，兩層缺一不可，原因如下：

- Whisper small 在 CPU 上專有名詞錯很多（GPT-6 Sol 聽成「JBT6 SOE」、官方聽成「光風」）。畫面上的官方截圖、字卡會把名字寫對，拿來校正。
- 有些資訊只在畫面上：價格表、對比數字、流程圖、嵌入的其他影片。逐字稿看起來語無倫次的段落，往往是畫面在播別的東西。
- 有些資訊只在口說：觀點、推論、語氣。

縮圖總表上小字看不清時，對那個時間點抽單張全解析度幀：

```
ffmpeg -ss 00:01:24 -i work/xxx/video.mp4 -frames:v 1 -q:v 2 work/xxx/keyframes/k_000124.jpg
```

通常 4 到 6 張單幀就夠，不要把 frames/ 全部一張張讀。

### 步驟 3：寫報告，照證據分層

報告寫到 `work/<平台>_<影片ID>/report.md`，格式見 `references/report-template.md`，骨架固定四層：

1. 元資料（平台給的）
2. 口說（字幕或轉錄，標明來源與已校正的誤聽）
3. 畫面（逐一抄錄字卡、UI、數字，附時間）
4. 社群（留言，未登入通常只有零星幾則，要說明不代表整體）

然後是「分析」：內容結構、立場判讀、可信度判讀、對使用者的價值。**每個判斷都要能指回某一層的證據**，這是本 skill 跟「AI 隨便看看」的差別。

交付時在對話裡給一句話結論、三到五個重點、報告路徑。不要把整份報告貼進對話。

## 判讀規則（四支實跑踩出來的）

| 現象 | 意思 | 怎麼辦 |
|------|------|-------|
| Whisper 回 0 段、幾秒就結束 | 影片沒口說，只有配樂。不是壞掉 | 看 sheets/，內容全在字卡上 |
| 關掉 VAD 後每 30 秒出現一個「You」 | Whisper 聽純音樂的幻覺 | 同上，確認無口說 |
| 逐字稿某段語無倫次 | 畫面在播嵌入影片或多段並排 | 看該時間的縮圖 |
| YouTube 繁中字幕像機翻 | 它就是機翻（英文自動字幕再翻一層） | 腳本已優先選原語言 -orig 字幕，別手動改用 zh |
| B 站或 FB 留言只有幾則、讚數全 0 | 未登入限流 | 報告註明「不代表整體」，別拿來下結論 |
| 口說「一分鐘做出」但畫面顯示「已處理 20 分鐘」 | 影片自己露餡 | 寫進可信度判讀，這就是分層的價值 |

## 平台差異

詳見 `references/platforms.md`。一句話版：YouTube 最順（有原語言自動字幕，15 秒搞定）、B 站元資料最大方（但常無字幕）、Facebook 最麻煩（無字幕、不登入拿不到讚與留言、下載器偶爾壞）。

## 耗時預期

純 CPU 跑 Whisper small，約需「口說時長的一半」。一分鐘短片 30 秒，四分鐘口播兩分鐘，半小時長片十五分鐘。無口說或有平台字幕的影片幾乎不等。第一次用某個 Whisper 模型會下載（small 約 500MB）。

## 驗證（交付前必跑，退出碼非 0 不交付）

```
python <skill 路徑>/scripts/validate_punct.py work/xxx/report.md
python <skill 路徑>/tests/test_grab.py
```

前者守全形標點與禁破折號，後者守凍結契約與純邏輯（字幕優先順序、無口說判定、自動安裝分支）。

## 三種模式

- 套用：貼連結，照預設跑，得到標準四層報告。
- 探索：指定目的（金句、競品、講義素材），報告的分析段依目的改寫，證據四層不變。
- 批量：一次多條連結，逐條跑腳本後出一份對照表（各支一句話結論＋數據），再問要深挖哪支。

每次交付後問使用者是否滿意。要補留言、換大模型重轉、對某段深挖，都可以在同一個素材包上加跑，不用重新下載。

## 凍結契約

brief.md 的四層標題字串、無口說標記句、字幕優先順序，定版於 v1.0，見 `FROZEN.md`。要改另開版本。