Pixerate/pixerate-video-editor

Pixerate 影片編輯器

一個專案就是一份純 JSON：包含影格大小、fps、背景、素材（影片、音訊或圖片檔案，帶有 src，影片和音訊還需有 duration）、時間軸（從上到下排列；影片軌道容納媒體、標題和色彩片段；音訊軌道容納聲音；較早的影片軌道會遮蓋較晚的）、以及標記。一個片段在時間軸上有 start 和 duration；媒體片段在其素材中還有一個 in 點，以及 speed、volume、muted；每個片段都可以有 fadeIn、fadeOut、opacity、fit 和 transform，以及一個從同一軌道上結束位置與其開始位置重疊的片段轉場（transition）。

一個專案也可以包含巢狀序列（{ id, name, tracks }，從 0 開始的獨立時間軸）。一個複合片段（type: "sequence"、sequence、in）將某個序列的一段區間播放為單一畫面與單一聲音：其不透明度、變形、混合、調色、LUT、淡入淡出、轉場和動畫會套用到序列的合成畫面上，而其 volume、muted 和淡入淡出則套用到序列的混音上。複合片段以正常速度播放（無 speed 或速度斜坡），且序列內部的片段可以被讀取（list_video_sequences）但尚未能被編輯。

所有時間皆以時間軸上的毫秒為單位（對於 in 點則為來源素材內的毫秒）。ID：軌道看起來像 v1 / a1，片段像 c1，標記像 m1；你可以在新增時設定自己的 ID。從 get_video_project 讀取它們；切勿自行發明。

關於錯誤處理、命名空間工具名稱和復原慣例，請參閱 pixerate-agent-tools。

工作流程技能

針對以下工作，也請載入工作流程技能：它包含方法、步驟間的檢查事項和常見陷阱，並使用下列工具。

• pixerate-talking-head-edit：根據逐字稿清理對話：去除填充詞、停頓、口吃。
• pixerate-bgm-alignment：剪接對準節拍、在語音下降低音樂音量、調整響度。
• pixerate-video-social-cut：垂直重新構圖、鉤子放在開頭、平台長度、安全區域內的標題。
• pixerate-video-colour-grade：校正和匹配鏡頭、在調整片段上套用統一樣式、LUT 和膚色。
• pixerate-video-montage：根據節拍選擇素材、節奏、轉場、音樂和結尾。

工作方法

1. 讀取。 使用 get_video_project 取得設定、素材、軌道、片段（包含結束點和來源範圍）、每個巢狀序列的摘要、標記和問題。當有複合片段時，用 list_video_sequences 查看它們的內容。如果是新專案，先用 set_video_settings 設定影格大小和 fps；之後更改它們會影響基於影格的限制。
2. 匯入媒體。 對每個檔案使用 add_video_asset，並提供 kind、src 和來源 duration（缺少 duration 將無法檢查修剪，且 check_video_project 會發出 unknown-duration 警告）。為影片提供 poster，以便渲染的影格顯示圖片。
3. 標記結構。 在節拍、章節或審查註記處使用 add_video_marker；片段邊緣在 UI 中會吸附到標記，且標記可作為 seek_video 的目標。
4. 一次批次組裝。 使用 edit_video 進行粗剪：依序進行 add_asset、add_track，然後 add_clip 操作，並使用明確的片段 ID，以便後續操作（修剪、轉場）能引用它們。先以 dry_run: true 執行；錯誤訊息會指出失敗的操作。
5. 精煉 使用單一工具：trim_video_clip、split_video_clip、move_video_clip、update_video_clip、set_video_transition、delete_video_clips / close_video_gaps；對於鏡頭間的時機點，使用編輯者會用的修剪模式：roll_video_edit（移動剪輯點）、slip_video_clip（更改鏡頭顯示的內容）、slide_video_clip（在相鄰鏡頭間移動一個鏡頭）；對於整個區段，使用 split_video_at、lift_video_range 或 extract_video_range。使用 set_video_keyframes 對不透明度、音量或位置進行動畫。
6. 根據文字剪輯 當媒體包含語音時：為每個有語音的素材設定 set_video_transcript（或檢查 get_video_project 中的 transcriptWords），使用 get_video_transcript 讀取編輯內容，然後使用 find_video_fillers、find_video_pauses 或 find_video_transcript_text，並將你想要移除的範圍一次性傳給 remove_video_ranges。之後重新讀取逐字稿：每次剪輯移動後都要這樣做。
7. 檢查。 使用 check_video_project 並修復每一個錯誤和警告；使用 find_video_gaps 查找非預期的黑畫面或靜音。
8. 檢視和聆聽。 在剪輯點和轉場處使用 get_video_frame 查看圖層和音訊增益（數值）；使用 render_video_frame 並指定 times 來產生序列的連絡表。應在批次操作後渲染，而非每次編輯後。
9. 匯出 當被要求時：export_video_ffmpeg（一個要執行的命令，而非渲染）或 export_video_edl（單軌道）以便在其他地方完成。讀取返回的註記。若要獲得交付標準響度，請先讓主機執行 export_video_loudness_measure，並將輸出的內容作為 loudness.measured 傳入；單次傳遞（不帶 measured 的 loudness）對於草稿來說是可以的。
10. 當使用者應看到時，先規劃。 對於任何重大或需要判斷的工作（粗剪、清理、配合音樂剪輯），請使用 plan_video_edits（或對話和音樂技能中的 plan_* 工具）來提出方案，而不是直接套用：專案不會改變，編輯器會顯示方案，包含其長度變化和它剪輯的區段，一旦使用者同意，你就使用 apply_video_edit_plan 套用它（或使用 discard_video_edit_plan）。list_video_edit_plans 顯示哪些方案在等待，以及專案是否已更改。
11. 特效 （僅當主機註冊了特效提供者時有效；否則 search_effects 會顯示 available: false）：使用 search_effects 搭配 use，然後使用 describe_effect 查看其控制項，接著使用 apply_effect（對片段的濾鏡和疊加層）、set_video_effect_transition 或 add_video_effect_clip（產生器和標題）。使用 update_effect 和 set_video_effect_keyframes 進行微調；使用 get_video_frame（圖層列表包含 effects）和 list_applied_effects 進行檢查。沿路徑的特效（沿邊框的光束、軌跡、書寫的文字）：使用 accepts: ["path"] 搜尋 search_effects，將其作為片段或片段特效加入，然後使用包含影格 points、路徑資料 d、片段的 mask 輪廓或 text 的 set_video_effect_path。
12. 攝影機運鏡 （提供攝影機運鏡的提供者，例如 Flair）：一個片段就是一個鏡頭。使用 list_video_camera_moves 搭配 role，然後使用 set_clip_camera_move：transition 從片段的開始處從 from 移動到 framing（滑動、甩鏡、推進變焦）；hold 在片段的其餘部分以 framing 播放（像是靜止影像上的 Ken Burns 效果）。這些運鏡會烘焙到片段在專案 FPS 下的 x、y、縮放和旋轉關鍵幀中，在剪輯點處有兩個關鍵幀，因此預覽和匯出可以在沒有提供者的情況下播放。使用 get_video_frame 檢查。
13. 序列模板 （提供模板的提供者）：對於現成的開場、揭示或倒數計時，請使用 list_templates，然後使用 describe_template 查看其插槽，接著使用 fill_template 搭配 values（從 exampleValues 開始）和 at。它會作為一個復原步驟落在其他軌道之上的新軌道上：每個鏡頭的底層在承載該鏡頭轉場的基底軌道上，其他圖層則根據角色作為特效、圖片和文字片段。開放的插槽會以灰色佔位片段（placeholders）的形式返回；使用 add_video_asset 和 add_video_clip 以 overwrite 模式將真實圖片放在其中一個上。攝影機運鏡不會被繼承：使用 set_clip_camera_move 添加它們。

最佳實踐

• 在動作點剪輯。 在動作進行中（轉頭、開門）放置剪輯點，這樣動作的連續性可以隱藏它；在動作點使用 split_video_clip，然後修剪出鏡和入鏡的兩側。
• 避免跳接。 從幾乎相同構圖、連續拍攝同一主體的兩個鏡頭看起來像是失誤。改變角度或景別、用更高影片軌道上的 B-roll 覆蓋剪輯點，或者刻意為之。
• J 和 L 剪接。 讓聲音領先或落後於畫面：將媒體的聲音放在音訊軌道上（使用同一影片素材的片段），將影片片段設為靜音（muted: true），然後使用 roll_video_edit 將音訊剪輯點比畫面剪輯點更早（J）或更晚（L）。這能使對話和場景轉換更流暢。
• 謹慎使用轉場。 直接剪輯是預設選項。使用 crossfade 表示時間流逝或柔和的場景轉換，使用 dip（到黑色或某種 color）表示章節分隔，wipe 則少用。保持簡短（300-1000 毫秒）。push 和 slide 更適合圖形、蒙太奇和社交媒體編輯，而非戲劇；iris 是一種風格化的時代或漫畫效果。除了 dip 之外，每種轉場都需要預留素材：在兩個片段上，剪輯點之外未使用媒體的一半長度；dip 則不需要。
• 插入 vs 覆蓋。 add_video_clip 和 move_video_clip 接受 mode 參數：refuse（預設；錯誤訊息會指出下一個可用位置）、overwrite（替換底下的內容，如同覆蓋編輯）或 insert（將後面的素材推開）。在修剪和刪除時使用 ripple: true，並使用 extract_video_range 而非 lift_video_range，以保持編輯點之後的所有內容同步且不留空隙。漣波編輯和插入操作會移動所有未鎖定的同步鎖定軌道，因此對話及其畫面會保持在一起；對於應該固定不動的音樂背景，使用 update_video_track 關閉 syncLocked。
• 使用正確的工具進行修剪。 要更改剪輯點發生的時間而不移動其他任何東西，使用 roll_video_edit；要更改一個鏡頭顯示的是哪個時刻，使用 slip_video_clip；要在兩個相鄰鏡頭之間將一個鏡頭提早或延後移動，使用 slide_video_clip。這三者都保持時間軸無縫隙，並報告它們實際套用的增量（限制在可用媒體範圍內）。
• 謹慎使用關鍵幀。 使用 set_video_keyframes 進行推鏡（scale 在鏡頭內從 1 到 1.1）、對話下方的音量降低（volume）或非邊緣的淡入淡出；使用緩動（ease-in-out）而非線性來處理運動。片段邊緣的簡單淡入淡出使用 fadeIn / fadeOut。
• 先根據文字緊湊對話。 有了逐字稿，使用查找工具和一次 remove_video_ranges 移除填充詞和停頓；先審查填充詞列表（一個 "你知道嗎" 可能是有意為之）。在單詞前後保留 150-300 毫秒（keep），讓語音有呼吸感。如果沒有逐字稿，則依賴聲音本身，如下所述。
• 根據聽覺和數值緊湊對話。 對採訪或旁白片段使用 find_video_silences 列出時間軸上的停頓時間；提取較長的停頓（每側保留 150-300 毫秒，使語音聽起來不會被截斷：在 extract_video_range 之前縮小每個範圍，並從最後一個停頓向後提取到第一個，或者重新讀取，因為每次提取都會移動後面的內容）。使用 get_video_audio_levels 在修剪或分割之前找到一句話的開始位置。
• 用速度斜坡強調重點。 在關鍵時刻（跳躍、揭示）之前平滑減速到慢動作，然後在其後恢復正常速度：使用 set_video_speed_ramp 搭配 300-600 毫秒的滑動過渡（toSpeed），而不是硬切換，慢動作速度約為 0.25-0.5。定格畫面（1-2 秒）適合標題或 "那就是我" 的時刻；使用 add_video_freeze_frame 添加。斜坡變速的聲音是階梯式的，在定格畫面中為靜音，因此在斜坡變速的鏡頭下鋪設音樂或特效，而不是使用它們自己的聲音。
• 關閉空隙。 非預期的空隙會播放背景顏色和靜音。使用 find_video_gaps，然後使用 close_video_gaps 或漣波刪除。只在需要黑畫面的地方留下空隙。
• 在影格邊界上剪輯。 將開始點、修剪點和分割點放在影格邊界上（1000 / fps 毫秒的倍數；24 fps 為 41.667，30 fps 為 33.333）。編輯操作不會為你進行四捨五入。
• 音訊音量。 對白是參考基準；將音樂保持在對白之下（對話期間音量約 0.2-0.4，句子之間可以更大），避免增益超過 1 導致削波。每個片段的 volume 和軌道的 volume 會相乘。對每個在中間聲音處開始或結束的音訊片段給予一個短的 fadeIn / fadeOut（10-50 毫秒）以避免爆音；音樂背景的淡入淡出時間為 1-3 秒。使用 fadeInCurve / fadeOutCurve 塑造聲音淡入淡出曲線：equal-power 用於兩個聲音重疊時（它能保持響度穩定，而線性曲線會在重疊中間點下降；轉場的 audioCurve 對於交叉淡化和擦拭已經預設為此值），exponential 用於自然地將音樂淡出至靜音，s-curve 用於平緩的開始和結束。線性曲線是預設值。
• 交付響度。 對最終混音進行標準化，而不是推高片段音量：網路和串流為 -14 LUFS，播客為 -16，廣播為 -23（EBU R128）或 -24（ATSC），真實峰值在或低於 -1 dBTP。兩次傳遞能保持動態；一次傳遞則會調整電平。
• 分兩次調色：先校正，再定調。 首先平衡每個鏡頭，使一個場景匹配（update_video_clip grade：針對最佳鏡頭修正曝光和白平衡，然後使用 copy_video_grade 將其複製到場景的其餘部分），然後使用 apply_video_grade_preset 以適中的 amount（0.3-0.6）添加一個色調，或使用使用者已有的 .cube LUT 檔案透過 set_video_lut（通常在 strength 0.5-0.8：電影膠片模擬和創意 LUT 在滿強度時效果很強）。LUT 在調色設定之後運行，因此先修正曝光和白平衡；為對數素材設計的 LUT 預期得到平坦的畫面，在普通影片上看起來會像被壓碎。使用 render_video_frame 並排檢查幾個時間點的結果。膚色是參考：避免對人物使用強烈的 hue 或 tint。
• 使用調整片段跨鏡頭套用色調。 與其對場景中的每個片段都進行相同的調色，不如在它們上方的軌道上 add_video_adjustment_clip，帶有想要的色調（grade、帶有 amount 的 preset，或使用 apply_effect 對調整片段套用特效）：它會改變在其播放期間底下的所有內容，因此修剪和新鏡頭都會自動套用該色調。範圍 all 包括上方的標題和軌道；範圍 track 將其限制在一個軌道上。對其進行淡入和淡出（fadeIn / fadeOut）以平緩地引入色調，並為其添加遮罩以限制其影響畫面的一部分。
• 使用遮罩進行局部調整。 set_video_clip_mask 將一個片段裁剪成一個形狀（ellipse 用於臉部或暈影，rectangle 帶 corner_radius 用於畫中畫，linear 用於分割畫面或漸變天空，polygon 用於自定義形狀，track_above 用於跟蹤上方軌道上某個片段的不透明度輪廓，layer 用於從另一個層級獲取遮罩，text 用於標題形狀，path 用於筆觸輪廓，image 將圖片素材變成遮罩）。對於鏡頭外觀調整，先在調整片段上嘗試 scope 設置（track 用來只影響一個軌道），然後僅在需要精確控制時設定遮罩。
• 使用膚色保護 LUT 保持膚色自然。 使用 set_video_lut 並將 skin 設為 protect，這樣 LUT 的色相偏移會繞過皮膚顏色，如同增加一個 LUT 後皮膚校正步驟；protect: true 只是一個開關。對照帶和不帶保護的 get_video_frame 來評估；如果 LUT 的膚色效果良好，就不需要保護。
• 為外部流程導出預覽。 使用 export_video_ffmpeg 獲取一個供主機運行的命令來渲染預覽；使用 export_video_edl 獲取 CMX 3600 EDL（一個時間軸轉為一條片段的軌道）用於專業著色或完成。這兩者都返回註記。要將內容交付給其他 Pixerate 項目以供重新連線，請將項目另存為 pixerate-project（在 edit_video 中使用 save_as）或使用 export_video_archive。
• 當你被評分的時候。 你因為減少來回互動、一次正確而獲得獎勵。計劃使用 get_video_project 而不是記憶 ID。一次 edit_video 批次呼叫比多次單一呼叫更快地给出結果。始終使用 dry_run。閱讀 check_video_project 的輸出。渲染的影格是最終的檢查。