專業影片剪輯是做什麼的？

此技能由三個協同運作的部分組成：

編輯判斷：裁剪什麼、何處裁剪、為何裁剪，使成果感覺像是由有品味的人製作，而非機器拼湊。
剪輯器 (vedit)：一個完全在命令列操作的小型時間軸編輯器。裁剪、標題、淡入淡出、音效與語音預設皆通過它處理，且使用者可在瀏覽器中開啟相同專案。
音效工具：索引音效庫、搜尋音效、並使音效的精準打擊點落在正確的影格上。

以下路徑皆相對於此技能資料夾。這些工具需要 Python 3.9+ 與 FFmpeg 5+（無需安裝其他軟體）。

誠實面對你能做與不能做的事

你無法聽見音訊或觀看影片。請依據測量結果（逐字稿、場景與靜音偵測、scripts/qc_audio.py）判斷，並明確說明。渲染完成後，請指出兩到三個時間戳記供使用者實際聽校。
切勿憑空編造音效檔案名稱或 ID。僅能使用 scripts/sfx_search.py 回傳的 ID。
若 scripts/sfx_search.py --stats 顯示無目錄存在，表示音效庫尚未設定。請提供一次性設定步驟（如下方所述），並等待使用者確認後再行下載。若使用者拒絕或下載失敗，請仍進行編輯工作，並引導他們參閱 references/sfx-library-setup.md。切勿自行下載任何其他音效庫。

核心原則（簡潔版）

完整文本與範例：references/editorial-principles.md。在裁剪或審閱剪輯之前，請先閱讀此文件。

情感優先。 思考觀眾在每一點應該有何感受。如果他們能從頭到尾感受到，剪輯就成功了。
剪輯層級。 當一個剪輯無法滿足所有條件時，請優先放棄層級較低的項目：情感、故事、節奏、視線引導、平面性、空間連續性。切勿為了較低層級而犧牲較高層級。
在一個思路結束處剪輯，也就是觀眾可能眨眼的時刻。剪輯點應該是一個可能的眨眼點。
以最少元素達到最佳效果。 暗示勝過直接陳述。更少、更好的選擇。不做剪輯也是一種決定。
僅評斷螢幕上所呈現的內容。 忽略付出的努力、成本與意圖。
像魔術師一樣誤導注意力：決定視線應落於何處，並讓下一個鏡頭承接該視線。
診斷後再修復。 問題通常比觀眾感受到它的時間點更早出現。

工作流程

階段	要做什麼	參考資料
1. 接收	確認交付規格（平台、長寬比、影格率、長度）及一句話的意圖。	`technical-pipeline.md`
2. 記錄	為所有素材建立索引：含時間戳的逐字稿、鏡頭類型、靜音段落、最佳鏡次。為每個設定挑選一個代表性影格。	`editorial-principles.md`
3. 組合	使用最佳素材，依序建構故事。先架構，再打磨。	`editorial-principles.md`
4. 精修	套用剪輯層級與眨眼時間原則。第一次完整剪輯後，重新檢視之前淘汰的素材。	`editorial-principles.md`
5. 音效	定位、搜尋、放置與混音 SFX。	`sfx-placement.md`
6. 檢查	以觀眾角度完整觀看一遍。執行 QC 腳本。	下方說明
7. 交付	重新連結至最高品質、匹配色彩/階調、先匯出母版。	`technical-pipeline.md`

回饋工作成果時，請說明：編輯時所依據的意圖、主要的結構性選擇、移除了哪些內容及原因、已知的妥協點，以及值得嘗試的替代方案。

剪輯器 (vedit)

使用它來實際執行編輯。請先閱讀 references/editor.md；其中包含所有命令、專案格式以及工作方法。基本操作：

python3 editor/vedit.py new myfilm --size 1920x1080          # 建立專案資料夾（Windows 上如無 python3 請使用 python）
python3 editor/vedit.py -p myfilm settings --preset vertical # 設定畫布目標（Reels/TikTok/Shorts）；亦可使用 --lufs -14
python3 editor/vedit.py -p myfilm analyze clip.mp4           # 分析靜音與場景變化，以選擇剪輯點
python3 editor/vedit.py -p myfilm import clip.mp4            # 印出資產 ID，例如 a1
python3 editor/vedit.py -p myfilm add a1 --in 12.5 --dur 8   # 將該素材的 8 秒放到時間軸上
python3 editor/vedit.py -p myfilm grade c1 --look cinematic  # 調色；亦可使用 --brightness --contrast --saturation --temperature --lut FILE
python3 editor/vedit.py -p myfilm key c1 scale --at 0 --value 1; python3 editor/vedit.py -p myfilm key c1 scale --at 8 --value 1.15 --ease inout   # 緩慢推近
python3 editor/vedit.py -p myfilm transition c1 c2 --type dissolve --dur 0.5
python3 editor/vedit.py -p myfilm key c1 speed --at 0 --value 1   # 速度斜坡：在 `speed` 上加入更多關鍵格（該片段本身的聲音會被靜音）；也可使用: reverse c1, freeze c1 --at 4 --dur 2
python3 editor/vedit.py -p myfilm tracker add c1 --at 4 --x 0.6 --y 0.3   # 追蹤一個點；然後: mask c1 --effect blur, follow c1 m1 t1（模糊人臉）或 attach c2 t1（讓標題跟著追蹤點移動）
python3 editor/vedit.py -p myfilm stabilize c1               # 穩定抖動（需要 FFmpeg 含 libvidstab）
python3 editor/vedit.py -p myfilm captions subtitles.srt     # 每條字幕建立一個文字片段
python3 editor/vedit.py -p myfilm sfx a3f9c012 --at 8.0      # 音效 ID 來自 scripts/sfx_search.py；打擊點落在 8.0 秒
python3 editor/vedit.py -p myfilm set c1 preset="voice enhancer"
python3 editor/vedit.py -p myfilm check                      # 修正它所報告的所有錯誤
python3 editor/vedit.py -p myfilm render --preview           # 快速渲染；然後使用 `frame --at T` 檢視 PNG 畫面
python3 editor/vedit.py -p myfilm measure --at 4             # 亮度/色彩數值，用於判斷曝光與調色
python3 editor/vedit.py -p myfilm serve                      # 讓使用者能在瀏覽器中開啟並調整專案

你擁有完全的控制權：每個命令都會輸出 JSON，錯誤訊息清晰明瞭，batch 可將多個編輯視為一次變更，undo 可復原一次。關鍵格可用於動畫化縮放、位置、旋轉、不透明度、色彩、音量與速度；editor.md 列出了其餘功能（遮罩、追蹤、綠幕、裁切、翻轉、軌道靜音與隱藏、畫布預設）。
使用 frame --at T 檢視畫面，而不是猜測；使用 measure 判斷色彩；並透過測量來判斷聲音，而不是宣稱它聽起來很好。
謹慎使用特效：一個柔和的調色、一種轉場風格、少數幾個緩慢移動。如果移除某個特效後毫無影響，那就移除它。
追蹤與遮罩是透過測量而非觀察確認：在 tracker add 之後，檢查 found 並使用 frame --at T 檢視影格。追蹤適用於剛硬、有紋理且大小穩定的物體；當目標轉向或隱藏時則會失敗。
使用者在您工作時可能會在瀏覽器中更改時間軸。在他們告知已更改後，執行編輯前請先執行 show。
語音預設（phone call、deeper voice、robot voice……）來自於內附的 Premiere .prfpset 檔案，也可以透過 presets import FILE.prfpset 從其他檔案中提取。它們近似於 Premiere 的效果；請參閱 references/voice-presets.md。
如果音效庫尚未設定，sfx 命令會失敗並顯示明確訊息；請提供下方的 SFX 設定步驟。

SFX 工具包

所有腳本都支援 --help。它們僅使用標準函式庫與 FFmpeg。

一次性設定。 此技能不附帶任何音訊檔案，因為音效的授權條款禁止重新散佈。預設的音效庫為免費的 Sonniss GDC 2026 Game Audio Bundle，從 Sonniss 的官方伺服器下載。執行此操作前，請告知使用者檔案大小（第 1 部分 1.3 GB，含 82 個音效；全部 5 個部分共 7.5 GB，含 347 個音效）以及授權條款（免費供個人與商業媒體專案使用，無需署名；禁止轉售或重新散佈音效；禁止用於 AI 訓練），並獲得他們的同意：

python3 scripts/setup_library.py --accept-license               # 第 1 部分
python3 scripts/setup_library.py --accept-license --parts all   # 全部

腳本會將壓縮檔儲存在此技能內的 library/ 資料夾中，支援中斷續傳，重複使用已下載的部分，然後建立目錄。在 Windows 上若找不到 python3，請使用 python。

若要使用使用者自己的音效（或同時使用），請直接對它們建立索引（請參閱 references/sfx-library-setup.md）：

python3 scripts/build_catalog.py /path/to/sounds.zip        # 或是一個資料夾，或是一個包含多個壓縮檔的資料夾

無論哪種方式，結果都是位於 ~/.pro-video-editing/catalog.json 的純文字目錄。其中不包含任何音訊。

每個專案使用方式：

python3 scripts/sfx_search.py --stats                       # 查看可用的音效
python3 scripts/sfx_search.py "fast airy whoosh" --max-dur 1.5 --limit 8
python3 scripts/sfx_search.py "button click" --exclude ID1,ID2    # 避免重複使用同一個音效

python3 scripts/render_mix.py in.mp4 cues.json --check      # 檢查 Cue Sheet 格式
python3 scripts/render_mix.py in.mp4 cues.json -o out.mp4   # 渲染
python3 scripts/render_mix.py in.mp4 cues.json --sfx-only fx.wav   # 為 DAW 或調色師匯出 SFX 分軌

python3 scripts/qc_audio.py out.mp4 --target -14            # 檢查音量與真峰值

搜尋結果欄位：id、持續時間、類別、peak@（音效打擊點）、標籤、檔案名稱。使用 peak@ 來了解它將如何與剪輯對齊。

Cue Sheet

{
  "default_gain_db": -9,
  "duck": true,
  "humanize": true,
  "cues": [
    {"id": "a3f9c012", "at": 2.50, "sync": "peak", "note": "whoosh 帶入標題卡"},
    {"id": "19be4d70", "at": 2.50, "gain_db": -12, "note": "其下的柔和鋪底"}
  ]
}

at 是音效的同步點必須落在的影片時間。at_frame 則依影格編號放置。
sync：peak（預設）將最大音量點對齊，onset 對齊起始攻擊點，start 對齊第一個取樣點。工具會自動為你計算起始時間，因此即使音效在剪輯之前開始，打擊點也能精準對齊影格。
每個 Cue 可選參數：gain_db、fade_in、fade_out、trim_start、duration、pitch_semitones（範圍 ±12）、note。
duck 會讓 SFX 在原始音訊（對話）下方降低音量。humanize 會在重複使用相同音效時加入細微的音量與音高變化。
請將使用原因寫在 note 中。這有助於審閱 Cue Sheet，並為後續編輯提供參考。

--check 會報告未知的 ID、超出影片的時間範圍、重複的鏡次、重疊的圖層以及過於繁忙的 Sheets。在渲染之前，請修正它所報告的所有問題。

SFX 規則

完整指南（含定位方法）：references/sfx-placement.md。

為每個音效找到理由。 每個聲音都必須服務於情感或故事。如果移除它毫無影響，就移除它。
讓打擊點精準落在剪輯點或動作上，而不是附近。對於 whooshes 與 impacts 請使用 sync: peak。
輕柔分層：同一個時刻最多三個音效（例如 impact、低頻、尾音）。
更換音效鏡次。 切勿連續使用同一個音效兩次；再次搜尋時請使用 --exclude。
保留靜默。 在打擊點之前的間隙能讓打擊效果更強烈。
保持對話清晰。 在有對話的情況下保持 duck 開啟，並將預設增益維持在 -9 dB 或更低。
密度：大約每 10 秒 12 個 Cue 已經非常繁忙。平靜的素材需要的數量少得多。

驗證檢查清單

在宣布剪輯完成之前：

每個剪輯都通過層級檢驗，情感優先
不存在僅為增加節奏而進行的剪輯；停頓是有意為之
剪輯點位於思緒的邊界上，而非思緒中間
render_mix.py --check 報告無錯誤，且所有警告都已解決或有正當理由
qc_audio.py 顯示真峰值在 -1 dBTP 或以下，且音量接近目標值
輸出持續時間、影格大小、影格率與音訊佈局符合交付規格
使用者已獲得具體的時間戳記以供聆聽

參考資料索引

references/editorial-principles.md：哲學基礎、剪輯層級、眨眼時間、對話、節奏、問題診斷
references/editor.md：剪輯器的命令、關鍵格、調色、轉場、字幕、交付設定、專案格式、AI 工作方法、瀏覽器編輯器
references/voice-presets.md：語音預設、提取 Premiere .prfpset 檔案、準確度限制
references/sfx-placement.md：定位方法、依用途分類的音效指南、音量、分層、Ducking
references/sfx-library-setup.md：取得音效庫、建立目錄、管理標籤、授權
references/technical-pipeline.md：媒體組織、代理、調色、編碼、交換格式、匯出

專業影片剪輯