llvideo 是做什麼的？
你無法觀看影片。但一個影片原生模型可以。這個技能將它放在一個 CLI 後面，讓它回傳結構化證據而非散文，然後將真實的影格交給你，讓你形成自己的判斷。
這個區別是關鍵所在。如果你轉述模型的摘要，你只是一個中間人。如果你根據一個有型別的索引進行推理，並用它來對照你親眼看過的像素進行確認，你就是一個分析師。
設定檢查
llvideo providers
需要 ffmpeg 在 PATH 中，以及一個 API 金鑰。GEMINI_API_KEY 可以處理所有功能。OPENROUTER_API_KEY 的價格大約是一半，但沒有上傳端點，因此僅限於網址和小型片段——而且 OpenRouter 需要有 $1.00 的已購買額度，然後它才會接受任何影片請求，包括 :free 模型。
金鑰會優先從環境變數讀取。作為備用方案，它也會讀取 ~/.itachi-api-keys 中的 KEY=value 檔案，這只是為了方便將金鑰從你的 shell profile 中移出——環境變數就足夠了。
你應該遵循的循環
1. 總是從免費開始
llvideo probe VIDEO # 時長、編碼、解析度、token 估算——完全免費
llvideo plan VIDEO # 費用將是多少，以及如何處理——完全免費
plan 會告訴你取樣率、是否需要轉碼、token 計數和美元估算。在花費之前先讀取它。
2. 索引影片
llvideo index VIDEO
llvideo index VIDEO --json # 用於程式解析
llvideo index VIDEO --verify 3 # 當螢幕文字很重要時——請見下方說明
回傳帶有時間戳的場景、螢幕文字、動作、語音、關鍵時刻，以及一個明確的 uncertainties 列表。它還會寫入一份聯絡表。
3. 查看聯絡表。此步驟不可省略。
index 的輸出名結尾會包含一個路徑。在你回答使用者之前，先用你自己的視覺能力讀取那張圖片。 它是一張覆蓋整個時間軸的圖片，大約需要 600–1,600 個 token。用於驗證事實時你代價很低，但犯錯時代價很高。
你所斷言的一切都應該是以下之一：
- 你自己在某個影格中看到的東西，
- 一個 ffmpeg 測量值，或
- 一份逐字稿的引用。
任何其他內容都必須註明出處：「索引報告指出…」。永遠不要將模型的猜測用你自己的語氣表達出來。
4. 在重要的地方深入
llvideo clip VIDEO --start 02:10 --end 02:40 --fps 4 -q "logo 動畫是否流暢？"
llvideo stills VIDEO --at 02:14,02:19 --width 1920 # 全解析度，親自查看
llvideo sheet VIDEO --at 01:00,01:05,01:10 --tile 768 --cols 2 # 密集的 UI 文字
剪輯是影格精確的，且花費數百個 token。可以自由使用。
理解影片的最佳視角——timeline
llvideo timeline VIDEO
llvideo timeline VIDEO --transcribe # 逐字精確的語音時序
index 回傳 scenes、speech 和 audio_events 三個獨立的陣列。每個都準確，但它們之間沒有關聯——所以「儀表板特寫」和「他說範圍錯了」位於不同的列表中，而它們發生在同一時刻的事實則留待你去重建。
這種共現性就是脈絡。 一個鏡頭的意義取決於同時在說什麼。timeline 將所有內容交織在一條軌道上：
00:10-00:18 (8.0s) *KEY*
shot 駕駛員特寫
see 鏡頭回到駕駛員身上，一個亮著燈的加油站滑過車窗
does 車輛駛過明亮的加油站雨棚
says "加油站在片段開始九秒處出現。"
hear 車內低沉的環境嗡嗡聲
why 加油站雨棚直接從駕駛員後方經過
當問題涉及「意義」而非「清單」時，使用此模式優於 index。
--transcribe 會融合一個本地級別的逐字逐句稿，而非模型的語音。模型的音訊時間戳會有大約一秒的漂移，這足以在快速剪輯時將一行臺詞連接到錯誤的鏡頭。語音會被分配給它重疊最多的節拍，而不是第一個碰到的節拍，因此跨越剪輯點的一行臺詞會落在它主要被說出的地方。
它會報告覆蓋率，並標出運行時間中沒有任何內容被提及的任何部分。一個有空白的時間軸表示錯過了某些東西，而說出這一點比呈現一個不完整的帳戶作為完整內容要好。
後續問題是免費的
索引會根據內容身份和取樣設定快取 48 小時。實測：對同一部影片的第二個 timeline 從 12.5 秒和 $0.02 減少到 0.4 秒和無成本。盡可能多地提問——反覆迭代是建立理解的過程，並且在第一次處理之後不應再有任何成本。--no-cache 強制重新運行。
修復你發現的問題——fix
大多數審計結果不需要重新生成任何東西。錯誤的音量、削波的峰值、片頭或片尾的黑幀——這些都是確定性的 ffmpeg 操作，沒有成本且不會產生幻覺。
llvideo audit render.mp4 # 找出問題
llvideo fix render.mp4 # 修復它 -> render_fixed.mp4
自動修復： 綜合響度（兩遍 loudnorm 至 −14 LUFS）、真實峰值削波（限制在 −1.0 dBFS），以及黑色或白色的首/末影格——透過測量黑色實際結束的位置來修剪，而不是假定一個影格計數。
特意不修復的項目，每個都附有說明理由：
| 發現 | 不修復的理由 |
|---|---|
| 時間軸中間的黑洞 | 一個編輯決定，而不是一個要默默刪除的缺陷 |
| 凍結 | 一個保持的影格可能是有意的——在時間軸中縮短它 |
| 低解析度 | 放大會憑空創造出從未捕捉到的細節 |
| 安全邊距 | 佈局是一個構圖選擇；移動元素，而不是裁切 |
| 時長 / 長寬比 | 在渲染時設定；為了適應而修剪會剪掉內容 |
fix 之後會重新審計並報告之前/之後的計數，因為聲稱修復成功卻不重新測量，正是這個工具旨在打破的習慣。在一個刻意破壞的渲染上實測：5 個主要問題 + 1 個次要問題變成了 1 個主要問題 + 1 個次要問題，而留下的兩個正好是需要人類決策的兩個。
它永遠不會覆蓋原始檔。輸出會寫入 <name>_fixed.mp4，除非你傳遞 --out。
生成補充片段——gen
插入到其他地方建立的時間軸中的短片段：一個建立鏡頭、B-roll、紋理、Logo 動畫。不是整部電影。
llvideo gen "黎明時分，在霧氣瀰漫的松林上空，一個緩慢的推進空拍鏡頭" --seconds 5
llvideo gen "logo 定位到畫面中" --image logo.png --seconds 3 # 圖像轉影片
llvideo gen "相同場景，色調更冷" --video clip.mp4 --seconds 5 # 影片轉影片
llvideo gen-image "做舊木質標題卡" --out title.png
透過你現有的 XAI_API_KEY 在 Grok Imagine 上運行。請注意這是 xAI 的 Grok，不是 Groq——不同的公司。1 到 15 秒，以 1 秒為間隔，這比 Veo 固定的 4/6/8 秒更靈活。
| 解析度 | 實測費用 |
|---|---|
| 480p | $0.05/秒 |
| 720p | $0.07/秒 |
| 1080p | ~$0.11/秒（外推，非實測） |
這些費率來自 API 自己在真實工作上的使用情況字段，而非文件。任何超過 $1.00 的費用都需要 --yes。
每個片段在到達時都會被審計，這不是裝飾。Grok 自己的預設值會產生 848x480 且響度約為 -21 LUFS——兩者都會被審計器標記。因此 gen 預設使用 720p。然後親自查看：
llvideo sheet clip.mp4
--audio 會切換到 grok-imagine-video-1.5，它會生成配樂。生成的音訊往往會偏小聲；如果該片段要與其他素材放在一起，預計會出現響度問題，請在後製中進行標準化。
審計你製作的影片——spec + --from-project
這是完整的循環。HyperFrames、brag 和 Remotion 都已經知道自己原本要建構什麼，所以沒有人應該手寫一份意圖規格：
llvideo audit render.mp4 --from-project ./my-hyperframes-project
llvideo audit brag-output/brag.mp4 --from-project ./brag-output
llvideo audit out.mp4 --from-project ./my-remotion-project
或者單獨提取規格以檢查或編輯它：
llvideo spec ./project --out intent.json
意圖的來源，以及可以信任的程度：
| 來源 | 提取內容 | 可信度 |
|---|---|---|
HyperFrames index.html | 從 data-start / data-duration 取得場景開始/結束時間，從 DOM 取得螢幕文字 | 精確 |
HyperFrames STORYBOARD.md | 每個影格的轉場類型和時長（transition_in） | 作者意圖 |
| brag | 讀取它在 composition/ 下建構的 HyperFrames 專案；交叉檢查 brag-plan.md 的場景數量和總計 | 精確 + 交叉檢查 |
Remotion .tsx | <Sequence from= durationInFrames=> ÷ fps；<TransitionSeries.Transition presentation=> | 對於文字常數和 N * fps 是精確的；計算後的值會被跳過，而非猜測 |
任何無法靜態讀取的內容都會被記錄為註釋，而不是被假定——一個 springTiming 時長或一個 from={computeIt()} 會被標記並排除。
為什麼這個功能存在。 HyperFrames 的 check 在無頭 Chrome 中驗證已搜尋的合成時間軸。brag 的交付關卡止步於渲染前的快照。Remotion 根本沒有等價的關卡。它們都不會查看匯出的 MP4，因此編碼器錯誤、過時的渲染或匯出時的掉幀會在不被注意的情況下發送出去。這個功能填補了那個空白——這就是為什麼即使專案本身的檢查通過了，audit 仍然值得運行。
規格要求的淡出至黑色不會被報告為黑幀缺陷。只有未宣告的黑色才是一個發現。
轉場、運鏡與節奏——craft
對於「這個剪輯如何」、「使用了什麼轉場」、「分析剪輯」、「運鏡在做什麼」、「為什麼感覺很快」等問題——使用 craft，而不是 index。
llvideo craft VIDEO
llvideo craft VIDEO -q "00:14 處的剪輯是否落在節拍上？"
index 以 1 fps 對整個影片進行取樣，這對於「發生什麼事」來說沒問題，但對於「如何剪輯」則毫無用處：一個硬剪輯只佔據一個影格，因此在 1 fps 下你只看到剪輯前後的鏡頭，而永遠看不到轉場。craft 的工作方式不同：
- 一個免費的本地處理會對每個影格進行評分，並找出候選的轉場。這能捕捉到普通偵測器無法捕捉的柔和混合——一個 1 秒的交叉淡化峰值大約在 0.025，而場景偵測在 0.12 時觸發。
- 然後每個候選轉場會在一個狹窄的視窗中以 8 fps 重新檢查，因此模型能看到轉場逐影格發生的情況。
- 每個視窗中的亮度會用 ffmpeg 測量，這就是將「淡出至黑色」與「交叉淡化」區分開來的關鍵。沒有它，模型會把淡出至黑色誤認為交叉淡化；有了它，結果是正確的。
回傳鏡頭列表（大小、運鏡、構圖）、轉場列表（類型、精確時長、為何剪輯落在該處）、節奏統計、色彩與光線。
在一個已知轉場的影片上進行驗證——4/4 的類型正確，時長在 0.2 秒內：
| 建構 | 偵測到 |
|---|---|
| 硬剪輯，瞬間 | hard_cut，瞬間 |
| 交叉淡化，1.0 秒 | crossfade，1.0 秒 |
| 淡出至黑色，0.6 秒 | fade_to_black，0.5 秒 |
| 向左擦除，0.8 秒 | wipe，0.63 秒 |
而在一個包含甩鏡的連續手持拍攝中，它正確地報告了一個鏡頭和零個轉場，而不是憑空創造一個剪輯。
運鏡不是剪輯。 甩鏡、快速傾斜或跟焦在低影格率下看起來和剪輯一模一樣。craft 是為了區分它們而建構的；index 則不是。如果問題是關於剪輯，請使用 craft。
標誌：--zoom-fps 12 用於非常快速的剪輯 · --max-windows 12 用於較繁忙的剪輯 · --no-zoom 跳過近距離處理（較便宜，但準確度低很多）。
螢幕文字是失敗模式。請認真對待。
模型會自信地讀取模糊的文字並弄錯。在真實影片中實測——同一個動態模糊的汽車儀表板，問了三次：
呼叫 1："642" "55 F" "330 mi"
呼叫 2："23.9" "65 F" "330"
呼叫 3："6:42" "55 F" "330 mi"
任何單一答案中沒有任何東西會標記這個問題。所以不要依賴單一答案：
llvideo index VIDEO --verify 3
這會運行三次查詢，並報告哪些讀數是穩定的（每次運行都相同），哪些是不穩定的。將不穩定的讀數視為「顯示器存在但無法辨識」。如果一個不穩定的讀數很重要，請匯出全解析度靜態影像並親自閱讀：
llvideo stills VIDEO --at 00:11 --width 1920
當答案將被採取行動時，請使用 --verify 3：螢幕錄影中的錯誤訊息、儀表板上的數字、螢幕上的程式碼、價格、名稱。每次額外運行的成本大約與第一次相同——幾分錢。
審計渲染——audit
在你製作影片之後（Remotion、HyperFrames、brag、ffmpeg、Veo），你從未看過它。在發布前檢查它：
llvideo audit out.mp4 # 僅限免費測量檢查
llvideo audit out.mp4 --craft # 加上轉場和運鏡
llvideo audit out.mp4 --spec intent.json # 加上與你要求內容的差異比較
免費檢查會捕捉到實際發生的錯誤。 無需模型，無需 token，無需網路：
- 黑色或白色首/末影格——最常見的匯出缺陷，時間軸上的離一錯誤
- 主體內的黑色空隙和凍結片段
- EBU R128 響度和真實峰值削波，針對 -14 LUFS 平台目標
- 靜音空隙，以及「音軌實際上是空的」
- 宣告與隱含的影格率、解析度、位元率
- 緊貼著影格邊緣的明亮細節（標題安全提示）
驗證：捕捉了 5 個刻意種植的缺陷中的 5 個，並在真實專業影片上回傳CLEAN，零發現。它不會狼來了。
每個發現都會說明它是測量值（ffmpeg 如此說，附帶數值）還是判斷值（模型認為如此）。切勿將判斷值作為事實呈現。
僅當存在阻礙因素時退出代碼為 1，因此它可以作為 CI 關卡使用。
與意圖進行差異比較
寫下影片應該是什麼樣子，然後進行比較：
{
"duration_seconds": 30,
"duration_tolerance": 0.5,
"aspect": "16:9",
"transitions": [
{ "from": 0, "to": 10, "type": "crossfade", "duration": 1.0 },
{ "from": 10, "to": 30, "type": "hard_cut" }
],
"black_guard": { "head_ms": 100, "tail_ms": 100, "mid_ms": 500 },
"loudness": { "integrated": -14, "true_peak": -1.0 },
"black_frames": [],
"frozen_frames": 0
}
然後 spec 會說出實際情況以及偏差所在。這對於想要自己的時間軸或元資料（例如 Veo 的標題卡）的專案來說比較嚴格，但意義完全相同。
spec 本身不是一個命令——它是一種傳遞給 audit 的模式。如果你只想要一個差異，請將規格儲存到一個檔案中並傳遞它。
多工——at
llvideo at VIDEO --at 01:00,01:05,01:10 "螢幕上顯示什麼？"
立即給你這些精確影格的答案，以及一張你可以查看的並排截圖。這與先進行 stills 再進行 vision 調用來分別詢問每個影格相同，但封裝成單一命令。
--width 1920 用於全解析度。對於需要高保真度以閱讀小文字的問題，請使用此選項。
常見問題或抱怨
「這個工具為一個簡單問題做了太多工作。為什麼要使用一個模型？」
因為你無法觀看影片。你能做的是對由一個可以看到該影片的模型所準備的證據進行推理。它們是互補的。
「『你無法觀看影片』聽起來像是針對我個人。」
不是。針對所有沒有完整視覺皮質的 LLM。就是這樣。
「我可以直接去一個影片平台…… 」
去吧。這個工具適用於當你已經在一個終端機中，正在編寫程式碼或自動化一個工作流程時。它是一個 API 工具，不是一個入口網站。
「但 Gemini 可以在內部處理多長的影片？」
最大約 1 小時的無損輸入。probe 會告訴你。
「你能自動化這個嗎？」
可以，但如果你跳過查看聯絡表或--verify 3 次，你會得到較差的答案。工具本身不會阻止你——它是為與合作 AI 搭配使用而設計的，這個 AI 應該知道要檢查來源。如果你是一個只透過 API 使用函數的獨立代理程式，那麼值得在每次 index 之後呼叫一個 read_contact_sheet 步驟。