snip — 影片剪輯與重組 是做什麼的?
將影片分割成片段、重新排列順序,並以指定的影格率輸出。 適用於製作精華片段、重新排序場景或調整影片節奏。
技能目錄(此 SKILL.md 所在位置)以下簡稱為 $SKILL_DIR。
使用時機
當使用者想要進行以下操作時,請使用此技能:
- 將影片切割成特定片段
- 以不同順序重新排列影片片段
- 移除影片中不需要的段落
- 變更輸出影格率(每秒剪輯數)
- 自動偵測語音段落以進行自然切割(優先)
- 自動偵測場景變化作為備用方案
設定(僅首次執行)
cd "$SKILL_DIR" && uv sync
代理工作流程
1. 詢問使用者
在剪輯影片之前,我需要知道:
📹 來源影片
列出影片檔案及其位置
✂️ 要切割的片段
對於每個片段,請指定:
- source: 檔案名稱
- start: 開始時間(秒,例如 0.0, 5.5)
- end: 結束時間(秒,例如 2.0, 10.0)
範例片段:
[
{"source": "video.mp4", "start": 0.0, "end": 1.0},
{"source": "video.mp4", "start": 3.0, "end": 4.5},
{"source": "video.mp4", "start": 1.5, "end": 2.5}
]
🎬 輸出 FPS(可選)
預設值:30 fps
常用選項:24, 30, 60
📁 輸入 / 輸出目錄(預設:./input 和 ./output)
等待使用者回應後再繼續。
2. 決定切割策略
優先順序:
- 明確片段 — 如果使用者提供了特定的開始/結束時間,則使用這些
- 音訊轉錄 — 如果
transcription.enabled: true(預設值),則尋找或產生轉錄,並在語音段落邊界處切割 - 自適應場景偵測 — 若轉錄不可用或失敗,則回退至此方法
音訊轉錄(主要方法)
技能將首先嘗試使用 音訊轉錄 來取得影片中的時間戳語音段落。這能產生與口語內容對齊的更自然切割。
🤖 音訊轉錄模式(優先)
剪輯器將:
1. 在 output_dir 中尋找現有的轉錄 JSON(例如 video_transcription.json)
2. 如果未找到,則自動執行音訊轉錄
3. 在語音段落邊界處切割影片
⚙️ 設定:
- transcription.enabled: true(預設值)
- fallback_to_adaptive: true(預設值)— 若轉錄失敗則使用場景偵測
- min_segment_duration: 每個片段的最小秒數(預設:1.0)
- max_segment_duration: 每個片段的最大秒數(預設:30.0)
範例設定:
{
"segments": [{"source": "video.mp4", "start": 0, "end": 60}],
"transcription": {
"enabled": true,
"fallback_to_adaptive": true,
"min_segment_duration": 1.0,
"max_segment_duration": 30.0
}
}
自適應場景偵測(備用方案)
如果轉錄功能關閉或失敗,技能將回退至視覺場景偵測:
🎬 自適應場景偵測(備用方案)
自動偵測影片中的場景變化以建立剪輯點。
這透過在自然轉場處切割,避免無聊、重複的內容。
⚙️ 偵測模式:
- adaptive — 最適合光線變化或漸變場景 [預設值]
- content — 最適合快速、清晰的場景切換
- threshold — 最適合淡入/淡出偵測
📏 場景持續時間過濾器:
- min_scene_duration: 每個場景的最小秒數(預設:1.0)
- max_scene_duration: 每個場景的最大秒數(預設:10.0)
🎛️ 進階(可選):
- threshold: content 模式的像素差異閾值(預設:27.0)
- adaptive_threshold: adaptive 模式的比率閾值(預設:3.0)
- window_width: 要平均的影格數(預設:2)
- min_scene_len: 切割前的最小影格數(預設:15)
- min_content_val: 最小內容變化值(預設:15.0)
使用自動偵測備用方案的範例設定:
{
"segments": [{"source": "video.mp4", "start": 0, "end": 60}],
"transcription": {
"enabled": false
},
"auto_detect": {
"enabled": true,
"mode": "adaptive",
"min_scene_duration": 1.0,
"max_scene_duration": 10.0
}
}
3. 編輯 config.json
根據使用者的選擇,寫入或更新 $SKILL_DIR/config.json。
4. 執行
cd "$SKILL_DIR" && uv run python scripts/cutter.py --config config.json
5. 回報結果
告知使用者輸出檔案路徑、時長和 FPS。說明使用了哪種方法(基於轉錄或場景偵測)。
設定參考
| 鍵 | 值 | 預設值 | 說明 |
|---|---|---|---|
input_dir | 路徑 | ./input | 包含輸入影片的資料夾 |
output_dir | 路徑 | ./output | 輸出資料夾 |
segments | 陣列 | (必要) | 片段定義列表 |
output_fps | 整數 | 30 | 輸出影格率 |
片段定義
| 鍵 | 型別 | 說明 |
|---|---|---|
source | 字串 | input_dir 中的檔案名稱 |
start | 浮點數 | 開始時間(秒) |
end | 浮點數 | 結束時間(秒) |
轉錄(優先方法)
| 鍵 | 值 | 預設值 | 說明 |
|---|---|---|---|
enabled | 布林值 | true | 啟用基於轉錄的切割 |
fallback_to_adaptive | 布林值 | true | 若轉錄失敗則使用場景偵測 |
min_segment_duration | 浮點數 | 1.0 | 跳過短於此值的片段(秒) |
max_segment_duration | 浮點數 | 30.0 | 跳過長於此值的片段(秒) |
自動偵測(備用方案)
| 鍵 | 值 | 預設值 | 說明 |
|---|---|---|---|
enabled | 布林值 | false | 啟用自動場景偵測(僅備用方案) |
mode | adaptive, content, threshold | adaptive | 偵測演算法 |
min_scene_duration | 浮點數 | 1.0 | 跳過短於此值的場景(秒) |
max_scene_duration | 浮點數 | 10.0 | 跳過長於此值的場景(秒) |
threshold | 浮點數 | 27.0 | content/threshold 模式的像素差異閾值 |
adaptive_threshold | 浮點數 | 3.0 | adaptive 模式的比率閾值 |
window_width | 整數 | 2 | 前後平均的影格數 |
min_scene_len | 整數 | 15 | 切割前的最小影格數 |
min_content_val | 浮點數 | 15.0 | 最小內容變化值 |
偵測模式(備用方案)
- adaptive(預設):最適合光線變化或漸變轉場的影片
- content:最適合具有清晰、銳利場景切換的影片
- threshold:最適合偵測淡入/淡出轉場
常用命令
# 預設設定(優先使用轉錄,否則回退至 adaptive)
cd "$SKILL_DIR" && uv run python scripts/cutter.py --config config.json
# 強制使用自適應場景偵測(跳過轉錄)
cd "$SKILL_DIR" && uv run python scripts/cutter.py --config config.json --no-transcription
# 自訂目錄
cd "$SKILL_DIR" && uv run python scripts/cutter.py \
--input /path/to/videos --output /path/to/output
輸出
每個設定會在 output_dir 中產生一個 output.mp4,包含拼接後的片段。
音訊會從原始影片片段中保留。
錯誤處理
- 未定義片段 → 顯示錯誤訊息,結束執行
- 無效的片段時間 → 顯示明確的錯誤,說明預期格式
- 找不到來源影片 → 顯示檔案未找到的錯誤
- 轉錄失敗 → 若啟用備用方案則回退至 adaptive,否則顯示錯誤
- 個別片段錯誤 → 記錄錯誤;其他片段繼續處理