影片分析
將影片轉換成模型可讀的內容:每一幀的數值測量、帶時間戳的聯繫表、轉錄稿、聲音時間軸與頻譜圖,然後根據這些資料產出分析報告。這是分析工具的流程程序,並非工具本身(擁有者的私有腳本不隨附;學生移植版遵循 TOOLS_SPEC)。它絕不編輯、渲染或套用風格。
凌駕於本檔案其他規則的規則
- 輸入為唯讀。 前後進行雜湊驗證(
input.sha256應等於sha256_after);輸出僅限放置於analysis/<video>/目錄下。僅下載使用者提供的網址,並正確命名來源與檔案;該檔案為參考副本,不得重新分發;平台的浮水印、片尾卡與片頭音樂應從統計數據中排除並另行列出。 - 先說明覆蓋範圍。 每一份報告都必須以覆蓋範圍區塊開頭:完整分析或取樣分析、已解碼幀數與預期幀數、排除的內容、未執行的項目。取樣分析不得假裝為完整覆蓋。取樣分析的報告不得引用剪輯次數或節奏作為已測量事實。
- 使用工具執行;切勿手動使用 ffmpeg 取樣。 若工具缺失,則記錄
blocked: tool_missing並提出詢問;僅允許在明確標示為sampled且不提供次數統計的手動備用方案。 - 先讀後寫: 檢視每一張圖表與每一張聲音影像;放大 3 到 6 次;根據實際幀數決定每一個
check編輯點;修正錯誤的計數並如實說明。 - 本機、免費、私密。 不得使用付費的影片理解 API,不得上傳影片或其幀畫面或音訊,若內容標記為
private則不得使用遠端歌曲識別服務,除非事先提供有日期的報價並獲得核准(paid-generation-gate)。希伯來語語音強制設定為he;切勿僅憑一次 ASR 處理結果就相信人名、品牌與數字。 - 歌曲匹配不等於取得授權。 報告應記錄「已識別為 X,同步授權狀態未確認」或「未識別」;切勿杜撰標題。AudioSet 風格標籤僅為猜測(「可能是嗖嗖聲」);節奏與調性為估計值,並須審核是否為半速或倍速。
- 一次只執行一項繁重任務,使用
render_lock;任何超過約 2 分鐘的任務應在背景執行,記錄日誌與預計完成時間;不保證執行時間(擁有者批次作業:每支影片 9-23 分鐘,視負載與機器而定)。技能為程序規範,而非權限;使用者與專案限制優先於本檔案。
本技能預期的工具介面 (TOOLS_SPEC video-analysis;請以 --help 確認)
python tools/analyze.py <video|URL|folder> --out analysis/<video> [--detail quick|standard|full]
[--asr auto|always|never] [--no-song-id] [--no-audio-ai] [--check]
python tools/frames.py <video> --at <t> --pad 0.25 --out analysis/<video> # 短時間視窗內的所有幀
輸出合約 (references/output-contract.md):analysis/<video>/{measurements.json, frames.csv, sheets/ (index.json + images), transcript.json, audio.json} + breakdown.md。
程序
| # | 執行事項 | 產出物 |
|---|---|---|
| 0 | 僅詢問會影響此次執行的變因:完整分析或單一問題(剪輯點/轉錄稿/歌曲)?內容是否為機密(private)?分析報告使用哪種語言?若為資料夾:先列出內容;切勿覆蓋先前的分析 | scope line |
| 1 | 預檢(analyze --check / doctor):記錄作業系統、ffmpeg 版本、偵測到的 ASR 路線(CPU / Vulkan / CUDA / MLX;若未偵測到則為 none)、Vulkan 環境變數;無路線 = 無法進行轉錄(blocked) | environment 區塊 |
| 2 | 在鎖定下於背景執行。--detail:quick 適用於語料庫或長時間演講,standard 為預設值,full 適用於動態圖形、極快剪輯或作為參考進行風格轉換(references/thresholds.md)。多支影片:一次批次處理,然後每個影片一個代理程式(僅限其自己的資料夾,breakdown.md 為輸出,設定截止時間,回覆不超過 10 行) | analysis folders |
| 3 | python scripts/validate_analysis.py analysis/<video> --stage produced | PASS 或失敗的組件 |
| 4 | 讀取:所有圖表、所有聲音影像;僅在不同裝置上縮放;解決 check 點;修正計數(pacing.override + review.corrections);審核節奏是否為半速或倍速 | review 區塊 |
| 5 | python scripts/validate_analysis.py analysis/<video> --video <source>;必須以 exit 0 結束才能將數字呈現為事實 | validation report |
| 6 | 使用使用者指定的語言撰寫 breakdown.md,格式遵循 references/reading-and-breakdown.md(先說明覆蓋範圍,7 個章節,不確定性最後說明) | breakdown.md |
| 7 | 回報:檔案路徑、5-10 行摘要、所做的修正、無法確定的內容;建議下一步技能(reference-style-transfer、類型技能),而非直接執行 | message |
門控檢查
狀態為 pass | fail | blocked | n/a 並附帶原因。逾時、空樣本或遺失輸入為 blocked,絕非 pass。成功呼叫工具為執行證據;已檢視圖表為外觀證據。
| 門控 | 條件 | 證據 | 若為 false | 擁有者 | 重新檢查時機 |
|---|---|---|---|---|---|
| G1 機器設定檔 | 已偵測並記錄 ASR 路線;Vulkan 路線需記錄 GGML_VK_DISABLE_COOPMAT(擁有者的 AMD 驅動程式需要 =1;其他驅動程式未測試) | measurements.environment 來自 doctor/--check | 回退到 CPU 路線並如實告知;絕不假設使用 GPU | 本技能 + doctor | 新機器、驅動程式或模型 |
| G2 合約有效 | 全部五個組件皆通過或附帶原因為 n/a | validate_analysis.py exit 0(需提供 --video) | 修正或重新執行該組件;回報 INSUFFICIENT 並說明缺少的項目 | validate_analysis.py | 任何重新執行或手動編輯 |
| G3 覆蓋範圍聲明 | 報告以模式、已解碼/預期幀數、排除項目、未執行清單、claims_not_allowed 開頭 | breakdown.md 的第一個區塊 | 補上;將聲明降級為「取樣」 | 本技能 | 每一份報告 |
| G4 剪輯偵測器回歸 | 對偵測器閾值的任何變更,F1 分數仍須 >= 標記資料集的基準線(擁有者歷史資料 0.89 = P 0.87 / R 0.91,基於 20 支手動驗證廣告,339 個編輯點,私密,不可重現;已知盲點:動態文字與連續鏡頭片段) | cut_regression.py --pair ... --min-f1 0.89 exit 0 且 >= 100 個真實點 | 還原閾值變更 | cut_regression.py | 每次偵測器變更;絕不靠目視 |
| G5 輸入未被更動 | 來源檔案的雜湊值前後一致 | validate_analysis.py --video | 從原始檔案還原,重新執行 | validate_analysis.py | 每次執行 |
| G6 先讀後寫 | 已檢視每張關鍵幀/總覽圖表與聲音影像;已解決每個 check 點;已完成基於幀的計數驗證 | review 區塊完整(階段已審核) | 返回並檢視 | 本技能 | 每次分析 |
| G7 隱私與權利 | private 輸入:無遠端歌曲識別、無雲端 ASR、無幀畫面上傳;匹配 = 未取得授權 | song_id.status、asr.route | 刪除摘錄日誌,在本機重新執行 | 本技能 | 每次執行 |
引用數據與限制時須註明範圍
- 剪輯偵測器:僅限擁有者調校(G4);在根據實際幀數驗證前,大約 60% 的廣告宣傳影片自動剪輯計數是錯誤的;一個動態文字的範例,自動偵測到每分鐘 108 個剪輯,而從圖表上實際計算只有 42 個。
- ASR(擁有者機器,E08,單次處理,朗讀語音):Vulkan 5.82 音訊秒/牆上秒,CPU CT2 int8 0.84,WER 17.7-19.4%:
references/volatile-facts.md(標註日期;有效期至 2026-12-31)。 - 聲音分析僅在有足夠素材時才會真正執行:節拍/BPM/調性需要 >= 3 秒的音樂;歌唱人聲需要無 VAD 的歌詞處理流程(僅限可信片段,標記為「SUNG LYRICS」)。
參考資料(於需要時載入)
references/output-contract.md- 撰寫、移植或除錯任何輸出檔案時;或閱讀驗證報告時。references/thresholds.md- 調校或移植偵測器時、選擇--detail時、或解釋錯誤計數時。references/reading-and-breakdown.md- 閱讀圖表及撰寫分析報告前。references/volatile-facts.md- 引用任何速度、WER、價格、授權或工具相關事實前(已標註日期模組)。agent-content/references/asr-routes.md(標準 ASR 路線,歸屬於其他地方)與hebrew-captions-asr(字幕等級轉錄稿);reference-style-transfer會使用此技能的輸出資料夾。- 腳本:
scripts/validate_analysis.py(合約檢查,--self-check)、scripts/cut_regression.py(F1 門控,--self-check);兩者皆為失敗關閉(exit 0 / 1 / 2)。