FFmpeg 影片編輯器

使用 ffmpeg 和 fftools.py 輔助腳本，從終端機編輯影片、音訊和圖片。

CLI 工具

所有操作都透過輔助腳本進行。可以在克隆倉庫的相對位置找到它，或在以下路徑：

SCRIPT="~/.claude/skills/ffmpeg/scripts/fftools.py"

所有輸出皆為 JSON 格式。

指令參考

# INFO — 取得檔案詳細資訊（時長、解析度、編解碼器、大小）
python3 $SCRIPT info input.mp4

# CUT — 擷取片段
python3 $SCRIPT cut input.mp4 output.mp4 --start 00:01:30 --end 00:02:45
python3 $SCRIPT cut input.mp4 output.mp4 --start 00:01:30 --duration 30

# MERGE — 合併多個影片
python3 $SCRIPT merge video1.mp4 video2.mp4 video3.mp4 -o merged.mp4
python3 $SCRIPT merge video1.mp4 video2.mp4 -o merged.mp4 --reencode  # 不同編解碼器

# EXTRACT AUDIO — 擷取音軌
python3 $SCRIPT extract-audio input.mp4 output.mp3
python3 $SCRIPT extract-audio input.mp4 output.opus --bitrate 128k

# SUBTITLES — 將字幕燒錄到影片中
python3 $SCRIPT subtitles input.mp4 output.mp4 --srt subs.srt

# RESIZE — 改變解析度
python3 $SCRIPT resize input.mp4 output.mp4 --width 1280 --height 720
python3 $SCRIPT resize input.mp4 output.mp4 --width 1920 --height -1  # 自動高度

# GIF — 影片轉動畫 GIF（雙重編碼，高品質）
python3 $SCRIPT gif input.mp4 output.gif --fps 15 --width 480
python3 $SCRIPT gif input.mp4 output.gif --start 00:00:05 --duration 3

# THUMBNAIL — 擷取單一影格
python3 $SCRIPT thumbnail input.mp4 thumb.jpg --time 00:00:30

# THUMBNAILS — 擷取 N 個等間隔影格
python3 $SCRIPT thumbnails input.mp4 --count 10 --output-dir ./thumbs/

# COMPRESS — 減少檔案大小
python3 $SCRIPT compress input.mp4 output.mp4 --crf 28 --preset medium
python3 $SCRIPT compress input.mp4 small.mp4 --crf 32 --preset fast  # 積極壓縮

# SPEED — 改變播放速度
python3 $SCRIPT speed input.mp4 fast.mp4 --factor 2.0    # 2 倍速
python3 $SCRIPT speed input.mp4 slow.mp4 --factor 0.5    # 半速（慢動作）

# WATERMARK — 加入圖片浮水印
python3 $SCRIPT watermark input.mp4 output.mp4 --watermark logo.png --position bottom-right

# TEXT — 燒錄文字疊加
python3 $SCRIPT text input.mp4 output.mp4 --text "第 1 章" --position center --size 72 --border
python3 $SCRIPT text input.mp4 output.mp4 --text "促銷中！" --position top-left --start 5 --end 15

# CONVERT — 轉換格式
python3 $SCRIPT convert input.avi output.mp4
python3 $SCRIPT convert input.mp4 output.webm --video-codec libvpx-vp9

# FRAMES — 將影格擷取為圖片
python3 $SCRIPT frames input.mp4 --output-dir ./frames/
python3 $SCRIPT frames input.mp4 --output-dir ./frames/ --every 30  # 每隔 30 幀

# AUDIO REPLACE — 更換音軌
python3 $SCRIPT audio-replace input.mp4 output.mp4 --audio music.mp3

# VOLUME — 調整音量
python3 $SCRIPT volume input.mp4 output.mp4 --level 2.0      # 音量加倍
python3 $SCRIPT volume input.mp4 output.mp4 --level 0.5      # 音量減半
python3 $SCRIPT volume input.mp4 output.mp4 --level 10dB     # 提高 10dB

# FADE — 加入淡入/淡出效果
python3 $SCRIPT fade input.mp4 output.mp4 --fade-in 2 --fade-out 3

# STABILIZE — 修正晃動影片（需 vidstab 濾鏡）
python3 $SCRIPT stabilize input.mp4 output.mp4 --shakiness 7 --smoothing 15

# TRANSCRIBE — 語音轉文字（含說話者標籤，離線；請參閱「轉錄」章節）
python3 $SCRIPT transcribe meeting.mp4                       # → meeting.json/.srt/.txt
python3 $SCRIPT transcribe meeting.mp4 --speakers 3          # 指定說話者數量
python3 $SCRIPT transcribe meeting.mp4 --no-diarize          # 僅轉錄，不辨識說話者

轉錄與分析 — 理解影片中說了什麼

使用 transcribe 指令，將會議錄音、訪談或任何語音影片/音訊轉換成帶有說話者標籤和時間戳記的逐字稿。這項工具專門用於回答「討論了什麼？」、「誰說了什麼？」、「摘要這場會議」或「找到他們談論 X 的地方」。

它100% 在本地和離線環境運作 — 音訊從不離開您的機器，無需雲端 API。底層技術： WhisperX (large-v3) 用於轉錄和詞級時間戳記，以及 sherpa-onnx 用於說話者辨識（無 token、開放 ONNX 模型）。

一次性設定（需要網路連線一次）

執行 /setup-transcribe 斜線指令，或直接執行：

bash ~/.claude/skills/ffmpeg/scripts/install-transcribe.sh

預設情況下，這會從 GitHub 發行版下載預先建置的套件（快速：無需模型審核，無需建置 PyTorch）並完整離線安裝；如果無法取得該套件（發行版遺失，或平台不支援），則會自動回退至從頭建置。它會建立一個隔離的 Python 3.12 虛擬環境（透過 uv）和所有模型；之後 transcribe 指令便無需網路。如果指令回報虛擬環境遺失，請執行此設定。

如果您想指定模式：

bash install-transcribe.sh --release   # 僅使用預先建置的發行版套件
bash install-transcribe.sh --build     # 僅從頭建置 (HF + PyPI)
HF_TOKEN=hf_xxx bash install-transcribe.sh --build   # 同時啟用 --diarizer pyannote

無網路環境 / 無法存取 HuggingFace？ 先在可連網的機器上建置一個自包含的套件，將其存放於任何位置，然後在無需 HF/PyPI 存取的情況下安裝：

# 在已執行 install-transcribe.sh 的機器上：
bash ~/.claude/skills/ffmpeg/scripts/make-bundle.sh ffmpeg-transcribe-bundle.tar.gz

此套件包含所有程式碼、模型、模型快取和 Python wheel。如果超過 2GB，它會自動分割為 <name>.part-aa、<name>.part-ab …（每個 <2GB）以符合託管/上傳限制。然後，在目標機器上（僅需 uv、ffmpeg 和 python3.12）：

# 單一檔案套件：
bash install-transcribe.sh --bundle https://your.server/ffmpeg-transcribe-bundle.tar.gz

# 分割套件 — 依序傳遞各部分（它們會自動串聯）：
bash install-transcribe.sh --bundle \
  https://your.server/ffmpeg-transcribe-bundle.tar.gz.part-aa \
  https://your.server/ffmpeg-transcribe-bundle.tar.gz.part-ab

（若要手動重新組合：cat ffmpeg-transcribe-bundle.tar.gz.part-* > ffmpeg-transcribe-bundle.tar.gz。）

使用方式

# 完整轉錄 + 說話者標籤（寫入 meeting.json, meeting.srt, meeting.txt）
python3 $SCRIPT transcribe meeting.mp4

# 選項
python3 $SCRIPT transcribe interview.mp4 --speakers 2          # 已知說話者數量 → 更高的準確度
python3 $SCRIPT transcribe call.m4a --language en             # 強制語言（跳過自動偵測）
python3 $SCRIPT transcribe lecture.mp4 --format txt           # 僅寫入 .txt
python3 $SCRIPT transcribe long.mp4 --model medium            # 較快，但較不準確
python3 $SCRIPT transcribe q4.mp4 --diarizer pyannote         # 更高品質的辨識器（需 HF token）
python3 $SCRIPT transcribe notes.mp4 --no-diarize            # 僅轉錄，不分離說話者
python3 $SCRIPT transcribe raw.wav -o ./out/session          # 自訂輸出基礎路徑

輸出格式

.txt — 人類可讀，按說話者發言分組。閱讀此檔案以理解內容：[00:03:12] SPEAKER_01: ...
.srt — 帶有說話者標籤的字幕，可燒錄回影片中（使用 subtitles 指令）
.json — 完整的結構化資料：每個區段和單字均附帶開始/結束時間與說話者，適合程式化分析（搜尋、時間軸、帶時間戳記的引用）

會議分析工作流程

# 1. 使用說話者標籤進行轉錄
python3 $SCRIPT transcribe meeting.mp4

# 2. 閱讀逐字稿以分析內容
#    （使用「讀取」工具檢視 meeting.txt，或解析 meeting.json 以取得時間戳記）

# 3. 從這裡開始，您可以進行摘要、提取行動項目、找出誰說了什麼，
#    或跳轉到特定時間點：將 JSON 時間戳記與 `cut`/`thumbnail` 配對使用。
python3 $SCRIPT cut meeting.mp4 clip.mp4 --start 00:12:30 --end 00:14:00

注意事項：

轉錄在 CPU 上執行（CTranslate2 在 Apple Silicon 上沒有 GPU 路徑），因此 large-v3 約為即時速度的 1–2 倍。一個 1 小時的會議約需 30–60 分鐘處理 — 適合在背景執行。使用 --model medium 或 distil-large-v3 可提升速度。
當您知道說話者數量時，傳遞 --speakers N 可明顯改善辨識效果。

標準工作流程

步驟 1 — 分析輸入

始終從取得檔案資訊開始：

python3 $SCRIPT info input.mp4

這會告訴您時長、解析度、編解碼器、檔案大小。利用這些資訊對輸出設定做出明智的決定。

步驟 2 — 執行操作

使用適當的指令。對於複雜的編輯，請串聯多個操作 — 將一個操作的輸出作為下一個操作的輸入。

步驟 3 — 驗證結果

在任何操作之後，檢查輸出以確認其運作正常：

python3 $SCRIPT info output.mp4

步驟 4 — 顯示結果

使用「讀取」工具顯示圖片（縮圖、影格）。對於影片，告訴使用者輸出路徑和檔案大小。

原始 ffmpeg — 用於進階操作

當輔助腳本無法滿足您的需求時，請直接使用 ffmpeg：

# 子母畫面 (PIP)
ffmpeg -y -i main.mp4 -i overlay.mp4 \
  -filter_complex "[1:v]scale=320:-1[pip];[0:v][pip]overlay=W-w-10:H-h-10" \
  -c:v libx264 -c:a copy output.mp4

# 並排比較
ffmpeg -y -i left.mp4 -i right.mp4 \
  -filter_complex "[0:v]pad=iw*2:ih[bg];[bg][1:v]overlay=W/2:0" \
  -c:v libx264 output.mp4

# 網格/馬賽克 (2x2)
ffmpeg -y -i a.mp4 -i b.mp4 -i c.mp4 -i d.mp4 \
  -filter_complex "[0:v]scale=640:360[v0];[1:v]scale=640:360[v1];
    [2:v]scale=640:360[v2];[3:v]scale=640:360[v3];
    [v0][v1]hstack[top];[v2][v3]hstack[bot];[top][bot]vstack" \
  -c:v libx264 grid.mp4

# 倒轉影片
ffmpeg -y -i input.mp4 -vf reverse -af areverse reversed.mp4

# 擷取特定音訊通道
ffmpeg -y -i input.mp4 -af "pan=mono|c0=FL" left_channel.wav

# 降噪
ffmpeg -y -i input.mp4 -af "afftdn=nf=-25" denoised.mp4

# 色彩校正（亮度、對比、飽和度）
ffmpeg -y -i input.mp4 -vf "eq=brightness=0.1:contrast=1.2:saturation=1.3" corrected.mp4

# 去背（綠幕移除）
ffmpeg -y -i greenscreen.mp4 -i background.mp4 \
  -filter_complex "[0:v]chromakey=0x00FF00:0.3:0.1[fg];[1:v][fg]overlay" \
  -c:v libx264 composited.mp4

# 從圖片序列製作縮時影片
ffmpeg -y -framerate 30 -i frame_%04d.jpg -c:v libx264 -pix_fmt yuv420p timelapse.mp4

# 從單張圖片 + 音訊製作影片
ffmpeg -y -loop 1 -i cover.jpg -i audio.mp3 -c:v libx264 -tune stillimage \
  -c:a aac -shortest output.mp4

# 兩個影片之間的交叉淡出（1 秒）
ffmpeg -y -i first.mp4 -i second.mp4 \
  -filter_complex "xfade=transition=fade:duration=1:offset=FIRST_DURATION_MINUS_1" \
  -c:v libx264 crossfade.mp4

CRF 品質指南

CRF	品質	使用情境
18	視覺無損	歸檔、專業編輯
23	高品質	預設 ffmpeg，適用於大多數情況
28	良好品質	建議用於分享，檔案較小
32	可接受	社交媒體，積極壓縮
38+	低品質	預覽、縮圖

CRF 值越低 = 檔案越大，品質越好。每增加 6，檔案大小約減半。

格式快速參考

容器	視訊編解碼器	音訊編解碼器	使用情境
`.mp4`	H.264 (libx264)	AAC	通用相容性
`.webm`	VP9 (libvpx-vp9)	Opus	網頁，較小檔案
`.mkv`	H.265 (libx265)	Opus	最大壓縮
`.mov`	ProRes	PCM	專業編輯
`.gif`	—	—	動畫，無音訊

錯誤處理

「No such file」 — 檢查輸入路徑，使用絕對路徑
「Unknown encoder」 — 編解碼器未編譯進。檢查 ffmpeg -encoders
「Permission denied」 — 輸出路徑不可寫入
「Avi header too large」 — 輸入檔案損毀，嘗試在輸入前加上 -fflags +genpts
Timeout — 影片太長。增加超時時間或使用 --preset ultrafast
Out of memory — 先降低解析度，再進行處理

beveradb/claude-code-config

claude-code-config 是什麼？

在你喜歡的 AI 中提問

說明文件

FFmpeg 影片編輯器

CLI 工具

指令參考

轉錄與分析 — 理解影片中說了什麼

一次性設定（需要網路連線一次）

使用方式

輸出格式

會議分析工作流程

標準工作流程

步驟 1 — 分析輸入

步驟 2 — 執行操作

步驟 3 — 驗證結果

步驟 4 — 顯示結果

原始 ffmpeg — 用於進階操作

CRF 品質指南

格式快速參考

錯誤處理

相關技能

steipete/video-frames

steipete/summarize

openclaw/openclaw

obra/superpowers

affaan-m/ECC

affaan-m/everything-claude-code

在你喜歡的 AI 中提問

說明文件

FFmpeg 影片編輯器

CLI 工具

指令參考

轉錄與分析 — 理解影片中 說了 什麼

一次性設定（需要網路連線一次）

使用方式

輸出格式

會議分析工作流程

標準工作流程

步驟 1 — 分析輸入

步驟 2 — 執行操作

步驟 3 — 驗證結果

步驟 4 — 顯示結果

原始 ffmpeg — 用於進階操作

CRF 品質指南

格式快速參考

錯誤處理

相關技能

steipete/video-frames

steipete/summarize

openclaw/openclaw

obra/superpowers

affaan-m/ECC

affaan-m/everything-claude-code

轉錄與分析 — 理解影片中說了什麼