Communitygithub.com

MelonTse/video-archive-skill

帮助用户在本地分析视频、明确压缩目标、比较小样,确认画质后批量压缩并整理原片归档。用于家庭录像和视频资料的压缩归档;不用于剪辑创作或未经验证的 HDR/Log 色彩转换。

video-archive-skill 是什麼?

这是一个用于视频压缩与归档的 AI 助手技能,专为家庭录像和视频资料优化。它运行在用户本地的 Python 3.9+ 环境中,依赖 FFmpeg 和 ffprobe,无需上传素材或使用模型 API Key,隐私安全。该技能首先检查环境并指导安装缺失的依赖,然后以只读方式扫描素材元数据,向用户报告数量、体积、时长等指标,并自动识别无法处理的文件(如 HDR、Log 素材)。接着,它会询问用户的使用目标(如家庭观看、长期保存等)并根据 quality.md 推荐 2–3 个候选 CRF 参数,生成包含代表性片段的小样。用户通过对比小样确认画质后,技能才会批量压缩并按照归档策略整理原片(默认保留原位,也可选择移动)。整个过程支持计划保存、断点恢复和失败复核,最终生成包含压缩率、原片位置等信息的交付报告。该技能目前主要面向 macOS,并优先处理 BT.709 色彩标准的 H.264/HEVC 素材。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MelonTse/video-archive-skill/tree/HEAD/.agents/skills/video-archive

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

視頻壓縮與歸檔

使用用戶自己的本地 AI 環境完成視頻壓縮。先檢查環境,再分析素材,詢問目標,推薦參數,提供小樣;收到用戶對具體小樣和批量範圍的確認後再批量執行,並指導歸檔。不要將「自動校驗通過」描述為用戶已經接受畫質。

配套腳本只依賴 Python 3.9+ 標準庫、FFmpeg 和 ffprobe。首版主要面向 macOS;執行依賴 POSIX 檔案鎖。普通聊天工具若無法讀寫本地檔案和執行命令,只能提供指導,不能宣稱已經處理視頻。腳本不需要模型 API Key,不上傳素材。

入口與任務目錄

  • 找到本 Skill 的絕對路徑。下文 <腳本> 指 scripts/workflow.py 的絕對路徑;<任務> 是用戶機器上新建的獨立任務目錄。不能把結果寫回已安裝的 Skill 包。
  • 在用戶原始素材目錄之外創建任務目錄;每批任務獨立保存清單、計劃、樣品、確認和狀態。新增或變更素材另建任務,已啟動批次保持原計劃。
  • 用戶明確的指令和已給出的授權優先於本 Skill 的默認建議。不要重複詢問已經確定的目標、路徑或選擇。用戶要求超出腳本支持範圍時,說明限制並準備單獨方案,不悄悄改腳本或降級處理。

1. 環境檢查與安裝指導

先確認終端能找到 Python,再運行 python3 "<腳本>" doctor。檢查 Python 版本、FFmpeg、ffprobe、libx265/libx264 和必要選項。缺失時讀取 environment.md,說明缺什麼、安裝方式及影響。用戶已經要求安裝則按該範圍執行;否則先提供具體命令讓用戶選擇執行方式。不得把缺失工具誤報成「無視頻」。安裝後複查到可用才繼續。

2. 唯讀分析素材

確認源目錄和輸出目錄,運行 init、scan,命令見 operations.md。掃描唯讀媒體元數據,不啟動編碼。向用戶報告數量、體積、時長、解析度/幀率、色深、色彩標記、音軌與主要 Profile,並單列無法讀取和需要複核的檔案。

BT.709 標籤不能證明拍攝模式,也不能排除 Log;結合用戶提供的拍攝資訊判斷。首版執行器僅自動處理 BT.709 標籤完整的 H.264/HEVC、4:2:0、8/10-bit 素材;HLG/PQ/HDR、字幕、多主視頻流和不明色彩單獨列為 REVIEW,不自動轉成 SDR。已知 Log 素材先單獨處理,不給用戶保證色彩正確。

3. 詢問使用目標

先解釋掃描發現,再只問尚不明確且會改變方案的問題:主要用途(家庭觀看/長期保存/繼續剪輯/分享)、畫質與容量的優先級、可接受的處理時間、播放設備或檔案大小限制。一般合併成一輪簡短問題;不要讓用戶填寫無關參數表。

歸檔同時說明兩種選擇:原片保留原位;或成功並複驗後移到原父目錄的指定子目錄。默認 keep,移動需要用戶明確選擇;不提供刪除原片功能。先確定該選擇,再生成樣品配置。

4. 推薦可比較的方案

按 quality.md 將用戶目標與實際素材聯繫起來。說明編碼器、preset、2–3 個候選 CRF、保留的參數、預期取捨和不確定性。不要把 CRF22、某相機或某目錄作為所有用戶的固定規則。

創建任務內 plan.json,格式見 operations.md。保存用戶目標與推薦理由;僅選擇本次有明確處理意圖的 Profile,每個選中 Profile 至少有一個小樣。挑選運動、紋理、暗部等代表片段;元數據無法識別場景時說明,並請用戶指定重點片段或協助觀看。素材類型很多時分批縮小範圍。

默認保持解析度、幀率、寬高比、方向、色深、已知色彩元數據並複製全部音軌。腳本只複製主視頻及音軌,輔助數據軌/封面不會進入壓縮副本,要在方案中說明。縮放、調色、HDR 轉換、音頻重編碼、硬體編碼、嚴格目標體積和剪輯中間格式不在首版自動執行範圍。

5. 小樣與人工觀看

運行 sample,展示 sample-report.md、reference 和各候選的本地路徑。所有候選從同一參考片段編碼。解釋容量與耗時,並指導對照觀看細節、運動、暗部、漸變、音畫同步及實際播放設備;關鍵幀裁切可能使時長略有偏移。

在用戶明確接受某候選前不運行 approve、run 或 start。用戶不滿意則調整計劃、重新小樣,再收集結論;不猜測「符合要求」。腳本的 PASS 是結構檢查,不是逐幀質量證明。

6. 確認後批量執行

展示 plan --crf N 的範圍與輸出映射、選中 CRF、歸檔策略和預計時間/容量的樣本依據。用戶確認可用並同意這批執行後,用 approve 記錄真實用戶回覆;已經涵蓋這些事項的回覆無需再問一遍。確認記錄可恢復上下文,但不等於腳本能證明回覆來自真人。

調用 start 後用 status 和日誌確認實際運行。批量單個 FFmpeg 順序處理;當前檔案完成編碼、驗證、歸檔後才能安全暫停。使用 pause;不通過殺進程正常暫停。resume 清除暫停請求,控制器退出後再 start;已有控制器運行時不再啟動。不要為長任務保持 AI 高頻輪詢。用戶要求以後通知時,才使用其 AI 系統提供的通知/調度能力。

參數、路徑、範圍或樣品變化會使舊確認失效;已啟動的任務按原方案恢復,變更另建任務。失敗與待複核項目單獨報告。斷點恢復以檔案為單位,未完成視頻從頭編碼。

7. 校驗與歸檔交付

按 archival.md 解釋壓縮版本、原片和任務記錄的對應關係。匯總已完成/跳過/待複核、壓縮副本的容量差、原片現址和恢復方式。報告中的壓縮率不等於實際釋放空間:原片仍保留,當前流程的磁碟佔用通常增加。

不覆蓋原片或既有輸出;未驗證的臨時檔案不作為成品交付。自動核驗基於 ffprobe、size/mtime,不是內容哈希或全片解碼檢測。用戶需要更嚴格驗證或備份時再設計相應步驟;移動目錄不是備份。保留任務目錄,使用戶或另一 AI 能恢復和解釋結果。

相關技能