Communitygithub.com

beatcut

用於從一組素材資料夾中的片段,根據音樂節拍剪輯短影片、建構或編輯節拍同步剪輯(shots.json)、選取片段進出點與節拍數,或使用 beatcut 命令列工具以 ffmpeg 渲染草稿或最終影片。涵蓋完整流程:初始化專案、偵測節拍網格、讓使用者在本機選取器中挑選片段(或手動編輯 shots.json)、檢查、渲染草稿、用聯絡表檢視,並在使用者核准後才渲染最終版本。

beatcut 是什麼?

beatcut 是一個專門的命令列工具,用於從一組原始影片片段和一首音樂檔案,自動產生與音樂節拍完美對齊的剪輯影片。它透過精確的節拍偵測與 frame-exact 剪輯,確保每個轉場都落在節拍點上。支援 Windows(Linux 與 macOS 未經測試),並提供完整的視覺化網頁選取器,讓使用者能以所見即所得的方式挑選片段、設定進出點與節拍數,並即時儲存。產生的影片可輸出為快速草稿或高品質最終版本,並支援自訂解析度、編碼器、填滿方式與色彩風格。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/faruk76150/beatcut/tree/main

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 之外,所有指令都以此專案資料夾為參數。

工作流程

  1. 詢問缺少什麼:片段資料夾、音樂檔案,以及輸出尺寸(預設草稿 1920x1080,最終版本 3840x2160;直式尺寸如 1080x1920 亦可)。
  2. 初始化:beatcut.py init <片段資料夾> --music <音樂檔案>。它會印出 created: <資料夾> 並將音樂複製到專案中。若顯示 project.json already exists,表示專案已存在;請直接使用,不要重新初始化。如須修改尺寸、fill、fps、encoder、exclude_prefix 或自訂 profiles,請編輯 project.json(詳見下方規則)。
  3. 節拍:beatcut.py beats <專案>。它會印出 period、t0 與 bpm,並將這些數值寫入 shots.json。偵測假設節奏穩定,t0 可能會有零點零幾秒的誤差。若結束碼為 1 且顯示 fewer than 4 beats were detected,請手動設定 period 與 t0(period = 60 / BPM;t0 = 第一個節拍的秒數)。告知使用者這些數值,他們可以在選取器中修正。
  4. 選擇片段,可使用以下任一方式:
    • 選取器(預設)。在背景啟動 beatcut.py pick <專案>(它會持續執行直到被停止;預設會開啟瀏覽器,除非加上 --no-open;預設連接埠 8765,可用 --port N 變更)。告知使用者它印出的 URL http://127.0.0.1:<port>/,以及該頁面會自動儲存。等待使用者表示完成,然後停止伺服器(Ctrl+C 或結束背景程序),再讀取 shots.json。選取器開啟時不要編輯 shots.json:網頁會覆蓋你的變更。
    • 手動編輯,當使用者要求你建構剪輯或提供確切的時間時使用。請遵循下方規則,然後執行 check。
  5. 檢查:beatcut.py check <專案>。結束碼 0 且顯示 ok: <n> shots, <s> s 表示無錯誤;也請閱讀警告(stderr)。在渲染前修復所有錯誤。
  6. 草稿:beatcut.py draft <專案>。它會印出 encoder: ...、segment i/n,最後是 out/<輸出名稱>_draft.mp4 的路徑。
  7. 檢視:beatcut.py sheet <影片> --out <某個 .jpg 路徑> 會產生一張 5x4 的聯絡表;開啟該圖片並向使用者描述結果(片段順序、色彩、淡入淡出、黑畫面、錯誤裁切)。選擇一個不在片段資料夾內的 --out 路徑,例如一個暫存資料夾。
  8. 最終版本,僅在使用者核准後:展示草稿後,詢問是否要渲染最終版本。只有在獲得明確同意後才執行 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 shotsshots 為空。請加入片段(透過選取器或手動編輯)。
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。

相關技能