13kailouis-stack/wecut

wecut は何をしますか？

wecut は、このマシンにインストールされた FFmpeg を使用して、JSON プロジェクトを MP4（または GIF）にレンダリングします。あなたが編集内容を記述し、WeCut が動画処理を行います。ネットワークサービスを呼び出すことはありません。

wecut が PATH にない場合は、代わりに npx -y wecut（Node 16以降）を以下のすべての場所で使用してください。WeCut が MCP サーバーとして接続されている場合、同じ手順がツール wecut_doctor, wecut_probe, wecut_validate, wecut_preview（フレームを画像として返す）, wecut_render, wecut_list, wecut_schema, wecut_example, wecut_analyze（フレームシートを画像として返す）, wecut_recipe_list, wecut_recipe_show, wecut_recipe_apply, wecut_recipe_from_project として提供されます。プロジェクトは project（オブジェクト）または projectFile（パス）として渡します。

ワークフロー

1. マシンを一度確認する: wecut doctor。FFmpeg が見つからないと報告された場合は、その hint に従ってください（例: sudo apt-get install -y ffmpeg）。
2. メディアをワークスペースに配置する。 プロジェクト内のすべてのパスは、wecut を実行したフォルダ（または --root DIR）からの相対パスです。URL は拒否されます。最初にファイルをダウンロードしてください。
3. メディアを確認する: wecut probe media/talk.mp4 media/music.mp3 で、長さ、サイズ、fps、オーディオの有無がわかります。これらの数値を from/to に使用します。
4. project.json を作成する（以下の形式）。wecut example podcast-clip で完全な例を出力します。wecut schema で JSON スキーマを出力します。wecut list で使用可能なすべてのスタイル、フォント、トランジション、フィルター名を表示します。
5. バリデーション: wecut validate project.json。エラーは JSON ポインタ（/clips/0/to）と hint とともに返されます。修正して繰り返します。
6. レンダリング前に確認する: wecut preview project.json --at 0.5,3,10 で小さな JPG フレームを out/preview/ に書き出します。開いてフレーミング、テキストサイズ、キャプションの位置を確認します。
7. レンダリング: wecut render project.json。高速な 540p チェックには --preset draft を、納品用にはデフォルトの final を使用します。

すべてのコマンドは 1 つの JSON オブジェクトを出力します。終了コード: 0 OK、2 無効な入力、3 依存関係不足、4 レンダリング失敗、5 制限超過。wecut render - で標準入力からプロジェクトをパイプできます。

プロジェクト形式

{
  "wecut": "1",
  "output": { "file": "out/clip-01.mp4", "ratio": "9:16", "res": 1080, "fps": 30 },
  "clips": [
    { "src": "media/talk.mp4", "from": 754.2, "to": 781.0, "focus": { "x": 0.42, "y": 0.5 } },
    { "src": "media/talk.mp4", "from": 795.5, "to": 812.0, "zoom": 1.15 }
  ],
  "texts": [
    { "text": "How I made my first $10k", "start": 0, "end": 3, "style": "hook", "y": 0.2, "in": { "type": "pop" } }
  ],
  "captions": { "words": "media/talk.words.json", "src": "media/talk.mp4", "style": "karaoke" },
  "audio": [ { "src": "media/music.mp3", "volume": 25, "loop": true, "duck": true, "fadeOut": 1.5 } ]
}

重要なルール:

• 2 つの時計。 クリップの from/to はソースファイルの秒数です。その他すべて（texts、overlays、audio.at、filters、effects）は完成動画の秒数です。wecut validate は完成した duration を出力します。
• トランジションは重なる。 クリップ N の transition はクリップ N+1 にブレンドされ、その duration だけ動画が短くなります。
• フレーミング。 デフォルトの fit は cover（埋めて切り抜く）です。focus（0..1; x 0.3 は左側を維持）と zoom で切り抜きを調整します。"fit": "contain" と "background": "blur" を使用すると、フレーム全体を表示できます。
• 位置 はキャンバスの割合で、0.5 が中央です。フォントの size は 1080p でのピクセル値です。
• 画像 は duration（デフォルト 3）を使用し、motion（in、out、left、right、up、down）を持つことができます。
• 絵文字 はテキストでは描画されません。PNG にして overlays で使用してください。

キャプション

単語タイミング付きの文字起こしを WeCut に渡すと、字幕が作成されます:

• words: .json、.srt、.vtt のパス、またはインライン配列 [{"word": "hi", "start": 0.1, "end": 0.4}]。OpenAI/Groq の verbose_json および whisper.cpp の JSON はそのまま読み取られます。
• src: 文字起こしが属する動画に設定します。これにより、文字起こしはソースファイルのタイムを保持し、WeCut はそのファイルからカットされた各クリップの出力タイムライン上にすべての単語を配置します（速度変更も含む）。src がない場合、タイムはすでに出力タイムである必要があります。
• style: classic、yellow、box-black、box-white、bold、comic、shadow（フレーズごと）、karaoke、karaoke-green（発話された単語がハイライト）、pop（大きな単語が一度に 1 つずつ表示）。

文字起こしが必要な場合: wecut doctor は、この FFmpeg が Whisper フィルタを持っている場合、local_transcription: true を報告します。それ以外の場合は、既存の音声認識サービスを使用し、その単語タイミングを JSON として保存してください。

テンプレート: うまくいったものをコピーする

レシピ とは、コンテンツを含まない編集の形状です。セクション（例: 見出しカード付きの 5 秒のフック、その後のトーク）、テキストスロット、キャプションと音楽のスタイル、エフェクトなどです。新しいクリップ、単語、音楽に適用するとプロジェクトが生成されます。

1. 効果のあった動画を分析する: wecut analyze media/viral.mp4 は、ショットとペース、最初の 3 秒のカット、フラッシュ、テンポ、ポーズ、無音のプラットフォームアウトロ（省略可能）、および sheet（各ショットのフレームを 1 枚の画像にまとめたもの）を返します。シートを見て、見出しカード、テキストスタイル、フレーミング、キャプションスタイルを確認します。
2. レシピを選ぶか作成する: wecut recipe list（組み込み: news-headline、news-headline-blur、quote-hook、vlog-phrases、podcast-punch、photo-slideshow、およびワークスペースの recipes/*.json）。wecut recipe show <name> は、そのロールとテキストスロットを一覧表示します。作成するには、wecut recipe schema に従ってください。
3. 適用する:

{
  "recipe": "news-headline",
  "clips": [
    { "src": "media/broll.mp4", "role": "hook" },
    { "src": "media/talk.mp4", "from": 120, "to": 165 }
  ],
  "texts": { "label": { "text": "ページ名" }, "headline": { "text": "一行で言う主張", "emphasis": ["claim"] } },
  "transcript": "media/talk.words.json",
  "write": "projects/clip-01.json"
}

wecut recipe apply --input request.json（または標準入力から JSON を取得する --input -）ですべてをチェックし、プロジェクトを保存します。その後 preview して render します。ロールのないクリップは body に供給されます。ロールのないセクションは、次のセクションのフッテージの先頭を借用します。

4. 独自のレシピを保存する: wecut recipe from-project projects/clip-01.json --name my-style --write recipes/my-style.json は、セクション、トランジション、テキストスロット、キャプションスタイル、エフェクト、およびデフォルトトラックとしての音楽を保持します。

音楽: レシピは独自のトラック（music.src）を持つことができ、CapCut テンプレートの曲のようにデフォルトで使用されます。"music": "media/song.mp3"（または動画。そのサウンドが使用されます）を渡して置き換えるか、"none" を渡します。他人の動画から取った曲は、アップロード後にプラットフォームによってミュートされる可能性があります。投稿時にアプリでトレンドのサウンドを追加すると、それを回避できます。

構造をコピーし、コンテンツはコピーしないでください。他のクリエイターのフッテージ、正確な文言、音楽はそのまま保持されます。

1 本の長い動画から複数のクリップを作成する

1. wecut probe でソースを調べ、単語タイミング付きの文字起こしを取得します。
2. 文字起こしを読み、適切な瞬間を選択します（判断はあなた次第であり、WeCut はコンテンツを評価しません）。
3. クリップごとに 1 つのプロジェクトを作成し、それぞれに captions.src をソースに設定します。これにより、1 つの文字起こしですべてのクリップに対応できます。
4. そのうちの 1 つを wecut preview して focus を調整し、次にそれぞれを wecut render します。

トラブルシューティング

• E_RANGE: to がファイルの終わりを超えています。wecut probe で実際の長さを確認してください。
• E_PATH: パスがワークスペース外であるか、URL です。
• E_MEDIA: ファイルが読み取り可能な動画、画像、またはオーディオファイルでないか、そのフィールドに適切な種類ではありません（clips 内の音楽、overlays 内の動画など）。
• E_DEPENDENCY: FFmpeg がないか、バージョン 6 より古いか、libass なしでビルドされています。wecut doctor を実行してください。
• レンダリングが遅すぎる場合: --preset draft、低い output.res、またはプロジェクトあたりのクリップ数を減らしてください。結果の render_seconds と realtime_factor で、このマシンでの速度がわかります。
• FFmpeg が正確に何を実行するか確認するには: wecut render project.json --dry-run。