shreyassaw5394/clip-anything

clip-anything 是做什麼的？

目的

將一個長篇錄影（單一檔案、多個檔案或一個代表單一會話的資料夾）轉換為頂尖的 N 個垂直精華片段，使用免費、本地的 clip-anything CLI。此技能驅動該工具，在實際剪輯前展示它會剪出什麼，並讀取報告讓使用者知道為何選取每個時刻。它絕不會將任何片段上傳、發布或傳送至任何地方；該 CLI 本身除了可選的一次性 Whisper 模型下載（會先詢問使用者）之外，不會進行任何網路呼叫。

先決條件

• 在 PATH 環境變數中要有 uvx（來自 uv）或 pipx。該 CLI 是一個 Python 套件；使用 uvx clip-anything 無需安裝即可執行。
• 在 PATH 環境變數中要有 ffmpeg 和 ffprobe。如果缺少它們，該 CLI 會以錯誤碼 3 退出並顯示安裝指令。
• 一個使用者可以指向的錄影：.mp4 .mkv .mov .m4v .ts .m2ts .mts .webm .avi .flv，或一個包含這些檔案的資料夾。

指令

從使用者的當前目錄開始工作。使用使用者提供的確切路徑；用引號包圍它們。不要移動、重新命名或刪除任何錄影。不要安裝超出以下步驟中作為建議貼出、供使用者自行執行的任何內容。

工作流程

（依序執行以下步驟；如果某個步驟無法完成，則報告該步驟而非跳過它。）

1. 檢查工具。 執行 command -v uvx || command -v pipx 和 command -v ffmpeg && command -v ffprobe。如果 uvx 和 pipx 都缺失，則印出以下訊息並停止： curl -LsSf https://astral.sh/uv/install.sh | sh（macOS/Linux）或 winget install astral-sh.uv（Windows）。 如果缺少 ffmpeg，則印出以下訊息並停止：brew install ffmpeg / sudo apt install ffmpeg / winget install Gyan.FFmpeg。 如果只有 pipx 存在，則在此檔案中所有出現 uvx clip-anything 的地方改用 pipx run clip-anything。
2. 解析輸入。 如果使用者指名了一個檔案或資料夾，就使用它。如果他們說「我的錄影」但沒有提供路徑，則在當前目錄中尋找影片檔案（搜尋上述副檔名，最新的優先）。僅當有數個合理的輸入或沒有任何輸入時才詢問使用者；否則直接進行並告知使用了哪個路徑。如果是一個資料夾，則直接傳遞：CLI 會將其視為一個會話。
3. 始終先進行乾式執行。 執行 uvx clip-anything "<輸入>" --dry-run --json 2>/dev/null（如果使用者指定了數量，則加上 --count N）。從標準輸出解析 JSON。顯示一個簡短的表格：排名、start 到 end 以 mm:ss 格式顯示、duration_s、score、若有 title 則顯示標題，以及來自 components 的頂尖構成要素。如果 clips 是空的，則直接說明，並在建議使用 --min-score 0 或更低的值之前，讀取 warnings（一個 below_floor 警告表示沒有任何片段超過動作門檻）。
4. 渲染。 除非使用者僅要求預覽，否則在不帶 --dry-run 和 --json 參數的情況下，使用相同的選項執行 uvx clip-anything "<輸入>"，以便顯示進度 UI。僅當使用者表示需要字幕且已同意一次性模型下載時，才加入 --yes 參數；否則讓 CLI 自行詢問。報告輸出資料夾（預設為 ./clips，或使用 --out 指定的路徑）。
5. 解釋挑選結果。 讀取 clips/report.json（直接讀取檔案，或使用 python3 -I -c 處理）。對於每個 ok 的片段給出一行說明：時間範圍、分數、以及哪些訊號促成了它（components：相對於基準的響度、音訊觸發、動態、音訊/動態一致性、靜態卡片懲罰、當存在時的口語獎勵）。當 layout 是 facecam 以及 captions 為 true 時，分別提及。以平實的語言列出 warnings 中的每一項；該工具會公開地降級，使用者應該知道。
6. 提供調整參數，每項一行，僅提供那些符合使用者所見情況的參數：
   • --count N 增加或減少片段數量（這是上限；安靜的會話會返回較少的片段）
   • --min-score 0.3 調低動作門檻；--min-score 0 讓檔案與自身比較排名
   • --min 20 --max 60 以秒為單位的片段長度範圍
   • --crop center 靜態中心裁切，而非跟隨動作
   • --no-captions 永遠不要燒錄字幕；--facecam off 關閉網路攝影機疊加層
   • --vision 使用本地 Ollama 進行重新排名和生成標題（實驗性；僅與 127.0.0.1:11434 通訊）
   • --force 覆蓋上次執行的片段；--no-cache 忽略快取的分析結果 使用不同參數重新執行只需要幾秒鐘，因為分析結果會快取在影片旁。
7. 揭露。 當存在字幕或標題時，說一次：字幕是機器轉錄（faster-whisper，本地執行），標題來自本地視覺模型；兩者都可能出錯，應在發布前檢查。

範例

• "從昨晚的直播做 5 個短影片，錄影在 ~/Videos/obs/ 裡" → 執行步驟 1，傳遞該資料夾，加上 --count 5 進行乾式執行，顯示表格，渲染，解釋。
• "為什麼它選取了一個載入畫面？" → 打開 report.json，顯示該片段的 components（一個高的 card 值表示靜態卡片懲罰被觸發，但響亮的音訊觸發仍然勝出），建議使用 --min-score 0.6 或在 --config TOML 中設定更高的 w_card。
• "只讓我看它會剪出什麼，不用渲染" → 僅執行步驟 1 到 3。

限制

• 以轉錄文字為主的時刻（一個沒有動作的笑話）分數本來就低；該工具優先考慮動作，口語只是獎勵。
• 動作門檻是根據兩個遊戲校準的；未見過的遊戲可能返回比要求更少的片段。請直接說明，而不是未經提示就強制使用 --min-score 0 來生成片段。
• 1080p60 的來源大約每小時分析 100 秒的內容；一個長達數小時的檔案需要等待，但不會卡死。
• 此技能不會編輯片段、挑選縮圖或發布到任何地方。發布是使用者自己的步驟。

故障排除

• 退出碼 2：錯誤的輸入（路徑不存在、不支援的檔案、沒有影片的資料夾）。顯示 CLI 的訊息。
• 退出碼 3：缺少 ffmpeg 或 ffprobe。根據步驟 1 中針對使用者作業系統的說明，印出安裝指令。
• 退出碼 1：沒有渲染任何內容。讀取乾式執行 JSON 中的 warnings；通常會是 below_floor。
• 字幕被寫入為外部 .ass 檔案而非燒錄進去：ffmpeg 建置版本缺少 libass（標準 Homebrew 配方）。將 ffmpeg-full 建置版本放到 PATH 中即可解決；其他所有功能依然正常運作。
• --vision 沒有生效：Ollama 未執行或沒有視覺模型；該次執行僅以動作為主繼續進行，並留下一條警告。