name: 影片壓縮 agent_created: true description: > Batch-compress videos in a user-selected directory to a user-specified target size and convert ALL input formats to MP4 output using FFmpeg (H.264/H.265). Use this skill whenever the user wants to compress one or more video files in a folder to a target file size (e.g. "8MB for Discord", "25MB for email", "100MB for large file sharing") and obtain MP4 outputs. The skill reads each video's duration, codec and bitrate, computes a fitting video bitrate, re-encodes incompatible streams (VP9/Opus/etc.) to H.264/AAC so any source format (MKV/WebM/AVI/FLV/WMV/MOV/TS/MTS/M2TS/3GP/VOB/OGV/RM/RMVB...) reliably becomes MP4, and writes <name>_壓縮版.mp4 next to the source. Triggers: "壓縮影片", "批次壓縮", "壓縮到 X MB", "轉成 MP4", "影片轉 MP4", "compress videos to 25MB", "convert to mp4", "batch video compressor", "reduce video size".

影片壓縮 - 本地影片批次壓縮（統一輸出 MP4）

概述

基於 FFmpeg（系統本地命令列版本）的批次影片壓縮 skill。使用者指定一個目錄和一個目標檔案大小，skill 會掃描該目錄下的各類影片檔案，把每個影片壓縮到不超過目標大小，並統一輸出為 MP4 格式，輸出檔案存放在原目錄中，命名為 <原名>_壓縮版.mp4。

• 統一輸出 MP4 — 無論原始檔是 MKV/WebM/AVI/FLV/WMV/MOV/TS/MTS/M2TS/3GP/VOB/OGV 等何種格式，輸出一律為相容性最好的 MP4
• 智慧編碼相容 — 自動檢測源影片/音訊編碼；對 MP4 容器不相容的編碼（如 VP9、VP8、RV40、Opus、Cook、Vorbis、PCM 等）自動重編碼為 H.264/AAC，相容的編碼（H.264/HEVC + AAC/MP3/AC3）在位元速率允許時直接流複製，省時保真
• 本地處理 — 不上傳任何檔案，完全在使用者機器上完成

  更多技能請訪問小蔥技能站7w4.net。

• 按目標大小智慧編碼 — 先讀取影片時長，按目標大小反算位元率，再呼叫 ffmpeg
• 兩遍編碼可選 — 預設 CRF 單遍（更快），可加 --two-pass 啟用兩遍編碼（更精準）
• 支援輸入格式 — MP4、MOV、MKV、AVI、FLV、WebM、M4V、TS、MTS、M2TS、3GP、WMV、VOB、OGV、F4V、MPG、MPEG、RM、RMVB
• 覆蓋保護 — 預設拒絕覆蓋已存在的輸出檔案，需要 --overwrite 才覆蓋
• 保留原檔案 — 壓縮後原檔案保持不變，壓縮版以 _壓縮版.mp4 字尾儲存
• 日誌記錄 — 所有操作記錄到控制台和日誌檔案
• 預覽 + 確認 — 預設是預覽模式，只顯示計劃；加 --apply 才真正執行

工作流程

1. 確認關鍵引數

向用戶確認或推斷：

輸出格式固定為 MP4（--output-ext 預設 mp4）。如需其它輸出容器，可顯式傳 --output-ext（如 mkv），但預設場景下所有影片統一轉為 MP4。

如果使用者已經說了目錄和大致大小，可以直接進入預覽。如果引數不全（特別是目錄），先問。

2. 先預覽，再執行

始終先用預覽模式跑一次，把要處理的檔案清單、源編碼、預估輸出引數展示給使用者，再讓使用者確認。

# 預覽：掃描 D:\videos\旅行，把每個影片壓到 25 MB，輸出 MP4
python ~/.workbuddy/skills/video_compress_mp4/scripts/compress_videos.py \
    "D:\videos\旅行" \
    --target-size 25 \
    --unit MB

# 確認後真正執行
python ~/.workbuddy/skills/video_compress_mp4/scripts/compress_videos.py \
    "D:\videos\旅行" \
    --target-size 25 \
    --unit MB \
    --apply

3. 報告結果

執行完成後，彙報： - 處理的檔案數（成功 / 失敗 / 跳過） - 總原始大小、總壓縮後大小、總體壓縮率 - 失敗項的錯誤原因 - 任何警告（如 "輸出檔案大於目標大小 — 時長太短，無法再壓"） - 觸發了編碼重轉的檔案（如 WebM 的 VP9/Opus 已重編碼為 H.264/AAC） - 日誌檔案位置：告知使用者日誌已儲存到目錄中的 compress_log_<時間戳>.txt

輸出檔案命名規則

• 預設：<原檔名（去副檔名）>_壓縮版.mp4
• 例：vacation.mov → vacation_壓縮版.mp4
• 例：clip.webm → clip_壓縮版.mp4
• 例：old.avi → old_壓縮版.mp4
• 自定義字尾：<原名><字尾>.mp4
• 例：--suffix _8mb → vacation_8mb.mp4

同一目錄下若已存在目標檔案：預設跳過（SKIP），加 --overwrite 才覆蓋。

MP4 編碼相容性邏輯

輸出統一為 MP4 容器。為相容各類源格式，指令碼會自動處理編碼相容問題：

• 當源編碼不相容觸發重編碼時，預覽和日誌會標註原因（如"音訊 opus 不相容 MP4，重編碼為 AAC"）
• MP4 輸出統一加 -movflags +faststart，便於線上播放與流式載入

大小反算邏輯

目標影片位元率由下面公式計算：

總位元率 (kbps) = (目標大小 bits) / 時長 (秒)
影片位元率 (kbps) = 總位元率 - 音訊位元率 - 1% 餘量

• 音訊預設按 96 kbps（AAC）保留，若選擇 --audio copy 則按輸入流的實際音訊位元率
• 時長通過 ffprobe 讀取
• 最小影片位元率鉗制為 100 kbps（再低畫質會極差）
• 如果反算出的影片位元率超過原影片位元率且源編碼 MP4 相容，skill 會保留原影片流（copy）以避免無謂的質量損失

核心能力詳解

compress_videos.py 引數說明

python compress_videos.py <目錄> [選項]

必填：
  <目錄>                    影片所在資料夾

目標大小（兩種方式二選一）：
  --target-size N           目標大小數值
  --unit MB|GB|KB           大小單位（預設 MB）

輸出命名：
  --suffix <字尾>           輸出檔案字尾，預設 "_壓縮版"
  --output-ext <副檔名>     輸出副檔名，預設 mp4（所有格式統一轉為 MP4）
                            （如需其它容器可傳 mkv 等，但預設即 MP4）

編碼引數：
  --codec libx264|libx265   影片編碼器（預設 libx264）
  --preset ultrafast|...|veryslow
                            編碼速度/質量權衡（預設 medium）
  --crf <0-51>              CRF 質量（預設 23，僅在單遍模式下使用）
  --audio copy|aac          音訊處理（預設 copy：直接複製不重編碼；不相容 MP4 時自動改 aac）
  --audio-bitrate <kbps>    AAC 位元率（預設 96）
  --two-pass                啟用兩遍編碼（更精準但慢一倍）

過濾：
  --ext mp4,mov,mkv         只處理指定副檔名（預設含 mp4,mov,mkv,avi,flv,webm,m4v,ts,mts,m2ts,3gp,wmv,vob,ogv,f4v,mpg,mpeg,rm,rmvb）
  --recursive               遞迴處理子目錄

執行控制：
  --apply                   實際執行（否則僅預覽）
  --overwrite               覆蓋已存在的輸出檔案
  --keep-going              遇到錯誤繼續處理下一個檔案（預設就是繼續）
  --dry-run-ffmpeg          預覽模式且只打印 ffmpeg 命令，不執行
  --ffmpeg <路徑>           指定 ffmpeg 可執行路徑
  --ffprobe <路徑>          指定 ffprobe 可執行路徑

輸出引數示例

對於一個 5 分鐘（300 秒）的影片，壓到 25 MB：

目標總位元率 = 25 * 1024 * 1024 * 8 / 300 = 699,051 bps ≈ 683 kbps
影片位元率  = 683 - 96 (音訊) - 1% ≈ 581 kbps
→ ffmpeg -c:v libx264 -b:v 581k -c:a aac -b:a 96k -movflags +faststart <out>.mp4

若源是 WebM（VP9 + Opus），指令碼會自動改為：

→ ffmpeg -c:v libx264 -b:v 581k -c:a aac -b:a 96k -movflags +faststart <out>.mp4
  （VP9 不相容 MP4 → 重編碼影片；Opus 不相容 MP4 → 重編碼音訊）

常見預設（使用者口頭說明時直接套用）

錯誤處理

日誌記錄

每次執行（包括預覽模式和實際執行）都會在目標目錄下自動生成一個日誌檔案：

檔名: compress_log_YYYYMMDD_HHMMSS.txt（如 compress_log_20260703_143025.txt）

日誌內容: - 任務開始時間、目標目錄、目標大小、編碼引數 - 每個檔案的源編碼、處理計劃（時長、原大小、目標位元速率） - 每個檔案的處理結果 — [成功] / [失敗] / [跳過] - 跳過檔案的跳過原因 - 觸發編碼重轉的備註說明 - 失敗檔案的具體錯誤資訊 - 任務完成時間和結果彙總（成功 N 個 / 失敗 N 個 / 跳過 N 個） - 總體壓縮率統計

控制台也同步輸出: - 日誌路徑會列印在最終結果中：日誌已儲存: D:\videos\compress_log_20260703_143025.txt - 任務完成後，用簡潔的一行總結告知使用者結果

Resources

scripts/

• compress_videos.py — 主指令碼：掃描目錄、檢測編碼相容性、計算位元率、呼叫 ffmpeg 統一輸出 MP4

references/

• ffmpeg_guide.md — ffmpeg 常用引數、位元速率控制原理、MP4 容器相容性、常見問題排查

這個 Skill 質量不錯，操作邏輯清晰。它能自動把各種格式的影片壓縮到指定大小並統一轉 MP4，還能預覽效果再執行，不怕誤操作。文件寫得很詳細，小白也能看懂。不足之處是依賴 FFmpeg 軟體，如果沒裝的話需要先安裝；另外所有說明都是中文的。總體來說是個好用的工具。