beatcut 是做什麼的?
beatcut 能將一組影片片段與一首音樂檔案,轉換成剪輯點精準落在節拍上的影片(frame-exact)。專案狀態儲存在專案資料夾中的兩個檔案:project.json(設定)與 shots.json(剪輯編輯)。命令列工具為 beatcut.py。
路徑
請使用已安裝所需套件的 Python 來執行命令(pip install -r requirements.txt;ffmpeg 與 ffprobe 必須在 PATH 環境變數中)。以此技能安裝的資料夾作為儲存庫資料夾:
python <技能資料夾>/beatcut.py <指令> ...
下文中的 beatcut.py 即代表該完整路徑。片段與專案的路徑可位於任意位置;若路徑含有空格,請用引號括起。專案一律位於 <片段資料夾>/beatcut;除了 init 與 sheet 之外,所有指令都以此專案資料夾為參數。
工作流程
- 詢問缺少什麼:片段資料夾、音樂檔案,以及輸出尺寸(預設草稿 1920x1080,最終版本 3840x2160;直式尺寸如 1080x1920 亦可)。
- 初始化:
beatcut.py init <片段資料夾> --music <音樂檔案>。它會印出created: <資料夾>並將音樂複製到專案中。若顯示project.json already exists,表示專案已存在;請直接使用,不要重新初始化。如須修改尺寸、fill、fps、encoder、exclude_prefix或自訂profiles,請編輯project.json(詳見下方規則)。 - 節拍:
beatcut.py beats <專案>。它會印出period、t0與bpm,並將這些數值寫入shots.json。偵測假設節奏穩定,t0可能會有零點零幾秒的誤差。若結束碼為 1 且顯示fewer than 4 beats were detected,請手動設定period與t0(period = 60 / BPM;t0 = 第一個節拍的秒數)。告知使用者這些數值,他們可以在選取器中修正。 - 選擇片段,可使用以下任一方式:
- 選取器(預設)。在背景啟動
beatcut.py pick <專案>(它會持續執行直到被停止;預設會開啟瀏覽器,除非加上--no-open;預設連接埠 8765,可用--port N變更)。告知使用者它印出的 URLhttp://127.0.0.1:<port>/,以及該頁面會自動儲存。等待使用者表示完成,然後停止伺服器(Ctrl+C 或結束背景程序),再讀取shots.json。選取器開啟時不要編輯shots.json:網頁會覆蓋你的變更。 - 手動編輯,當使用者要求你建構剪輯或提供確切的時間時使用。請遵循下方規則,然後執行
check。
- 選取器(預設)。在背景啟動
- 檢查:
beatcut.py check <專案>。結束碼 0 且顯示ok: <n> shots, <s> s表示無錯誤;也請閱讀警告(stderr)。在渲染前修復所有錯誤。 - 草稿:
beatcut.py draft <專案>。它會印出encoder: ...、segment i/n,最後是out/<輸出名稱>_draft.mp4的路徑。 - 檢視:
beatcut.py sheet <影片> --out <某個 .jpg 路徑>會產生一張 5x4 的聯絡表;開啟該圖片並向使用者描述結果(片段順序、色彩、淡入淡出、黑畫面、錯誤裁切)。選擇一個不在片段資料夾內的--out路徑,例如一個暫存資料夾。 - 最終版本,僅在使用者核准後:展示草稿後,詢問是否要渲染最終版本。只有在獲得明確同意後才執行
beatcut.py final <專案>。最終版本較慢且檔案較大。報告輸出路徑。
如果使用者之後修改剪輯,請回到步驟 4。渲染會重複使用已快取的片段,因此第二次草稿會更快。
手動編輯 shots.json
請保持檔案為有效的 JSON(UTF-8 編碼)。check 會回報所有違反下列規則的情況。
頂層:
version:1。period:數字,大於 0.05 且小於 10。t0:數字,0 或以上。tail:0 到 30(預設 1.5)。shots:列表,最多 2000 個。- 可選:
bad(片段名稱對應到列表,列表元素為{"a": s, "b": s, "note": ""},其中b > a >= 0)、clipnotes(片段名稱對應到文字)、markers({"beat": int >= 0, "title": 文字};僅在選取器中顯示)。保留你不認識的鍵;工具會保留它們。
每個片段:
clip:包含副檔名的檔案名稱,必須與片段資料夾中的名稱完全相同。不可包含/或\,不可包含:。必須是clips_dir中的檔案,且符合extensions設定。in(0 或以上)與out(大於in):在原始片段中的秒數。beats:整數,1 到 512。- 可選,有預設值:
fit(fit或cut;預設fit)、interp(oflow、blend、none;留空以自動選擇)、prof(內建名稱neutral、warm、cool、contrast、golden,或是在project.json的profiles中定義的名稱;預設neutral)、tin(cut、fade、fadewhite;預設cut)、tdur(0 到 5 秒,預設 0.5)、note(文字,最多 2000 個字元)。
數值的用途:
- 片段會依序播放;片段 N 佔據節拍網格上從
t0 + period * (前方所有節拍總和)開始的beats個節拍。第一個片段從其in點開始於影片的第 0 幀,因此它也會涵蓋第一個節拍之前的時間,並會讀取超過其out點。 fit:速度 =(out - in) / (beats * period)。速度在 0.015 內接近 1 視為 1 倍速。check會拒絕速度低於 0.1 倍或高於 8 倍。若要以fit保持正常速度,請設定out = in + beats * period。cut:以 1 倍速播放;out不用於計算速度(選取器會寫入out = in + beats * period)。請同樣處理。- 最後一個片段會延長
tail秒,並在tail時間內淡出畫面。整個剪輯不得長於音樂長度。 - 每個片段都需要足夠的原始素材直到其結束點(包括
tail與第一個片段的前導部分),並且在片段結束前需有 0.1 秒的餘裕。fade或fadewhite轉場會從其前後片段各借用一半長度,因此前面的片段需要超過其out點的素材,後面的片段則需要在其in點之前的素材。 - 轉場必須比前後片段都短。
tdur會四捨五入到偶數幀數;少於 2 幀表示直接剪接。 - 慢動作:自動插值僅在片段播放速度低於 0.97 倍且原始幀率乘以速度低於輸出幀率時發生(草稿使用
blend,最終版本使用oflow)。除非使用者要求,否則不要設定interp。 - 選擇
in/out時,請確保範圍不與bad區域重疊;check會在重疊時發出警告。
project.json 規則(當你修改它時):
- 未知的鍵會導致錯誤。
music的路徑相對於專案資料夾,不可包含..,也不可以是絕對路徑。draft與final的格式為{"width": n, "height": n},且 n 為正偶數。fps為字串,例如"25"或"30000/1001"。fill:cover或blur。encoder:auto、cpu或nvenc。loudness:-40 到 -5。 profiles:名稱([a-z0-9_-],1 到 32 個字元)對應到一個 ffmpeg 濾鏡鏈,不可包含;、[或]。片段僅能透過名稱引用設定檔。
訊息與處理方式
警告以 warning: 開頭,不會中斷渲染。錯誤以 error: 開頭,會輸出到 stderr。
| 訊息 | 含義與處理方式 |
|---|---|
ffmpeg was not found on PATH; install FFmpeg and try again (exit 2) | ffmpeg 或 ffprobe 不在 PATH 中。請使用者安裝 FFmpeg;除非被要求,否則不要自行安裝。 |
no project.json in <folder> (did you mean <folder>\beatcut?) (exit 1) | 你傳入了片段資料夾。請使用其內部的 beatcut 資料夾。 |
unknown key(s): ...、<field>: must be ... | project.json 中的某個欄位無效。請修正該欄位。 |
<path>: invalid JSON (...) (<path> 為 shots.json 的完整路徑) | 檔案中有語法錯誤。請修正;之前的版本可能儲存在 shots.json.bak。 |
shots[i].<field>: must be ... | 某個片段違反了上述規則(i 從 0 開始計數)。請修正。 |
no shots | shots 為空。請加入片段(透過選取器或手動編輯)。 |
shot N (clip): clip not found in the clips folder | 檔案名稱錯誤,或檔案不存在,或被 extensions 或 exclude_prefix 排除。請檢查拼寫;切勿為了修復而建立或複製檔案到片段資料夾中。 |
shot N (clip): needs source up to X s but the clip is Y s long | 範圍加上前導部分、結尾或轉場超過了片段長度。請將 in 往前移、使用較少的節拍、使用 fit 搭配較短的 out,或縮短轉場。 |
shot N (clip): needs X s before the start of the clip; move `in` later | 第一個片段的前導部分或轉場延伸到 0 秒之前。請將 in 延後,或縮短轉場。 |
shot N (clip): shorter than its transitions; ... | 轉場比片段還長。請減少 tdur 或增加節拍數。 |
shot N (clip): speed X is outside 0.1x-8.0x | 範圍與節拍數不匹配。請變更 beats 或調整範圍。 |
the edit is X s long but the music is only Y s | 請移除節拍或片段、降低 tail,或使用更長的音樂檔案。 |
warning: shot N (clip): uses a range marked bad (...) | 片段與 bad 區域重疊。請移動它,或告知使用者。 |
warning: <clip>: HDR source (...); colours will look washed out ... | HDR 片段;beatcut 不支援色調映射。請告知使用者;建議使用 SDR 片段。 |
warning: <clip>: cannot be read (...) | ffprobe 無法讀取該片段。請告知使用者。 |
music file not found: <name> | music 檔案在專案資料夾中遺失。 |
profile <name>: ffmpeg rejects the filter chain | 自訂設定檔有誤。請在 project.json 中修正其濾鏡鏈。 |
too many shots to assemble in one pass (N); split the edit | 剪輯太長,無法一次渲染完成。請告知使用者;將其拆分為多個專案或減少片段數量。 |
another render is already running for this project (exit 2) | 有另一個渲染程序(可能從選取器啟動)正在執行。請等待它完成;不要刪除 work/ 資料夾。 |
cannot write <file>; close it in any player and try again | 輸出檔案正在其他地方被打開。請使用者關閉它。 |
fewer than 4 beats were detected; set period and t0 by hand (exit 1) | 請參閱步驟 3。 |
結束碼:0 成功,1 使用者輸入有問題(修正後重新執行),2 環境或執行時期錯誤。
禁止事項
- 請勿修改、移動、重新命名或刪除原始片段,且除了
init建立的beatcut專案資料夾外,請勿在片段資料夾中寫入任何內容。工具寫入的所有內容都位於專案資料夾內。 - 請勿刪除
project.json、shots.json或音樂檔案。請勿對已存在的專案再次執行init。 - 請勿在使用者看過草稿並核准之前執行
final。 - 請勿將選取器暴露到網路:不要設定連接埠轉發、隧道、反向代理,也不要嘗試將其綁定到其他 IP。它僅監聽
127.0.0.1,且不防護同一台電腦上的其他程式。 - 請勿將濾鏡鏈放入
shots.json,也請勿在選取器執行時編輯shots.json。 - 請勿在未檢視草稿(聯絡表或影片本身)的情況下聲稱結果良好。
- 請勿承諾工具不具備的功能:無 HDR 色調映射、無人臉偵測、無 CapCut 匯出、無音效。Linux 與 macOS 未經測試;支援的測試平台為 Windows。