Communitygithub.com

beatcut

ユーザーがクリップのフォルダから音楽のビートに合わせて短い動画をカットしたり、ビート同期編集(shots.json)の作成・編集、クリップのイン/アウトポイントとビート数の選択、beatcut コマンドラインツールを使用したドラフトや最終動画のレンダリングを行いたい場合に使用します。プロジェクトの初期化、ビートグリッドの検出、ローカルピッカーでのショット選択(または shots.json の手動編集)、チェック、ドラフトレンダリング、コンタクトシートでの確認、ユーザーの承認後の最終レンダリングまでをカバーします。

beatcut とは?

beatcut は、クリップのフォルダと音楽ファイルから、フレーム単位でビートに合わせてカットされる動画を生成するツールです。プロジェクトの状態は、`project.json`(設定)と `shots.json`(編集内容)の2つのファイルに保存され、コマンドラインツール `beatcut.py` で操作します。主なワークフローは、プロジェクトの初期化、ビートグリッドの検出、ショット選択(ブラウザ上のピッカーまたは手動編集)、チェック、ドラフトレンダリング、コンタクトシートによる確認、そしてユーザーの承認後の最終レンダリングです。各ショットには、クリップ、イン/アウトポイント、ビート数、フィット方法、トランジションなどを細かく設定でき、レンダリングは再利用可能なセグメントキャッシュにより高速化されています。Windows でテストされていますが、Linux や macOS でも動作する可能性があります。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/faruk76150/beatcut/tree/main

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

beatcut は何をしますか?

beatcut は、クリップのフォルダと音楽ファイルから、フレーム単位でビートに合わせてカットされる動画を生成します。状態はプロジェクトフォルダ内の2つのファイル project.json(設定)と shots.json(編集内容)に保存されます。コマンドラインツールは beatcut.py です。

パス

必要なパッケージがインストールされている Python(pip install -r requirements.txt; ffmpeg と ffprobe は PATH に含まれている必要があります)でコマンドを実行します。このスキルがインストールされているフォルダをリポジトリフォルダとして使用します。

python <skill folder>/beatcut.py <command> ...

以下では、beatcut.py はそのフルパスを意味します。クリップやプロジェクトへのパスは任意の場所に置くことができます。スペースが含まれる場合は引用符で囲んでください。プロジェクトは常に <clips folder>/beatcut です。init と sheet を除くすべてのコマンドはこのプロジェクトフォルダを引数とします。

ワークフロー

  1. 不足しているものを尋ねる: クリップフォルダ、音楽ファイル、出力サイズ(デフォルトは1920x1080のドラフト、3840x2160の最終版; 1080x1920などの縦サイズも可能)。
  2. 初期化: beatcut.py init <clips folder> --music <music file>。created: <folder> と表示され、音楽ファイルがプロジェクトにコピーされます。project.json already exists と表示された場合は、プロジェクトが既に存在します。そのまま使用し、再初期化しないでください。サイズ、fill、fps、encoder、exclude_prefix、カスタム profiles を変更する必要がある場合は project.json を編集します(以下のルールを参照)。
  3. ビート検出: beatcut.py beats <project>。period、t0、bpm を表示し、shots.json に書き込みます。検出は一定のテンポを前提としており、t0 が数百分の1秒ずれることがあります。fewer than 4 beats were detected で終了コード1が返された場合は、period と t0 を手動で設定します(period = 60 / BPM; t0 = 最初のビートの秒数)。ユーザーに数値を伝え、ピッカーで修正してもらうことができます。
  4. ショットの選択: 次のいずれかの方法で行います。
    • ピッカー(デフォルト)。beatcut.py pick <project> をバックグラウンドで起動します(停止するまでブロックします。--no-open を追加しない限りブラウザを開きます。デフォルトポートは8765、--port N で変更可能)。ユーザーに表示された URL http://127.0.0.1:<port>/ と、ページが自動保存されることを伝えます。ユーザーが完了したと言うまで待ち、サーバーを停止(Ctrl+C またはバックグラウンドプロセスを終了)して shots.json を読み込みます。ピッカーが開いている間は shots.json を編集しないでください。ページが変更を上書きします。
    • 手動編集。ユーザーが編集の構築を依頼したり、正確な時間を指定した場合に行います。以下のルールに従い、その後 check を実行します。
  5. チェック: beatcut.py check <project>。終了コード0で ok: <n> shots, <s> s と表示されればエラーなしです。警告(stderr)も確認してください。レンダリング前にすべてのエラーを修正します。
  6. ドラフト: beatcut.py draft <project>。encoder: ...、segment i/n と表示され、最後に out/<out_name>_draft.mp4 のパスが出力されます。
  7. 確認: beatcut.py sheet <video> --out <some .jpg path> で5x4のコンタクトシートを生成し、その画像を開いて結果をユーザーに説明します(ショットの順序、色、フェード、黒フレーム、誤ったクロップなど)。--out パスはクリップフォルダ外(スクラッチフォルダなど)を指定してください。
  8. 最終版はユーザーの承認を得てから: ドラフトを確認した後、最終版のレンダリングをユーザーに確認します。明確な承諾を得た後にのみ beatcut.py final <project> を実行します。最終版は遅く、ファイルサイズも大きくなります。出力パスを報告します。

ユーザーが後で編集を変更した場合は、ステップ4に戻ります。レンダリングはキャッシュされたセグメントを再利用するため、2回目のドラフトは高速です。

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": text}。ピッカーでのみ表示)。不明なキーは保持されます。ツールはそれらを保存します。

各ショット:

  • 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 個のビートを占有します。最初のショットはビデオフレーム0から in ポイントで始まるため、最初のビートより前の時間もカバーし、out を超えて読み取られます。
  • fit: 速度 = (out - in) / (beats * period)。1に近い速度(0.015以内)は1とみなされます。check は0.1倍~8倍の範囲外の速度を拒否します。fit で通常速度にしたい場合は、out = in + beats * period と設定します。
  • cut: 1倍速で再生されます。out は速度に使用されません(ピッカーは out = in + beats * period と書き込みます)。同様に設定してください。
  • 最後のショットは 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} で、正の偶数です。fps は "25" や "30000/1001" のような文字列です。fill: cover または blur。encoder: auto、cpu、nvenc。loudness: -40~-5。
  • profiles: 名前([a-z0-9_-]、1~32文字)から1つの 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範囲に先行部分、tail、トランジションが加わってクリップの長さを超えています。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編集が1回のレンダリングには長すぎます。ユーザーに伝え、複数のプロジェクトに分割するか、ショット数を減らします。
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 を実行してはいけません。
  • ピッカーをネットワークに公開してはいけません: ポートフォワーディング、トンネル、リバースプロキシは使用せず、別のアドレスにバインドしようとしてはいけません。ピッカーは 127.0.0.1 のみでリッスンし、同じコンピュータ上の他のプログラムから保護されていません。
  • shots.json にフィルタチェーンを配置してはいけません。ピッカー実行中に shots.json を編集してはいけません。
  • ドラフト(コンタクトシートまたは動画自体)を確認せずに結果が良いと主張してはいけません。
  • ツールにない機能を約束してはいけません: HDR トーンマッピング、顔検出、CapCut エクスポート、サウンドエフェクトはありません。Linux と macOS は未テストです。Windows がテスト済みプラットフォームです。

関連スキル