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