FCPXML経由のFinal Cut Pro編集
何かに触れる前に
編集の前には必ず inspect してから diagnose してください。タイムラインにはファイル名だけではわからない構造があり、誤った前提で編集すると元に戻すのに大きなコストがかかります。
inspectでアクションanalyze_timelineを使い、形状、長さ、解像度を確認する。diagnoseでアクションvalidate_timelineを使い、ギャップ、フラッシュフレーム、重複を確認する。- 何かを変更する前に、
preview://<path>リソースを読んでタイムラインを実際に見る。これにより、接続クリップがそれぞれのレーン行に表示された自己完結型のHTMLタイムラインがレンダリングされ、プライマリ・ストーリーラインだけでなくBロールやオーディオレイヤーも確認できる。
7つのグループ
| グループ | 使用用途 |
|---|---|
inspect | 読み取り専用の理解。必ずここから始める。 |
diagnose | 問題を見つける：ギャップ、フラッシュフレーム、無音、重複、ビート。 |
edit | クリップを変更する：挿入、削除、トリミング、分割、並べ替え、再タイミング、無音除去。 |
mark | マーカーとチャプター。SRT/VTTやビートのインポートを含む。 |
generate | 新しい構造を構築する：ラフカット、モンタージュ、A/Bロール、テンプレート、およびビデオ用途のカットリストからの import_edl_json。 |
transcript | ローカルで文字起こしし、発言内容に基づいて編集またはクリーンアップする。transcript_pack はすべての撮影を1ページにまとめる — 対話編集を計画する前に読むこと。すべてのアクションは話者ラベルとオーディオイベントのために backend: "elevenlabs" を取る。これはメディアをElevenLabsにアップロードし、ELEVENLABS_API_KEY が必要。デフォルトの local はマシンから出ない。 |
deliver | 他のNLEに書き出す、再フォーマット、再リンク、FCPにプッシュする。 |
preview | 編集を見る：プロキシレンダリング、コンタクトシート、およびソースメディアから読み取ったフィルムストリップ＋波形。 |
watch | ラウンドトリップを閉じる：オペレーターのCmd-E書き出しに気づき、最後のものとdiffする。 |
index | 分析キャッシュ。index_status はキャッシュの古さを示す。index_build はタイムライン内のすべてのソースをウォームアップする。index_clear はキャッシュを削除する。何もこれに依存しない。 |
scenes | 画素からショット境界を検出する。detect_scenes はソース時間とタイムライン時間の両方でクリップごとのカットをリストする（[scenes] 経由でインストールされている場合はPySceneDetect、それ以外はffmpegの粗いシーンフィルタ）。scenes_to_markers は各カットにマーカーを配置する。scenes_split はそこでクリップを分割する。結果はインデックスにキャッシュされる。 |
organize | バルクライブラリロギングと台帳。organize_auto はキャッシュされたキャプションと文字起こしからクリップごとにキーワードを提案する（apply=true で書き込む）。clip_name グロブ、keyword や role でクリップを選択し、organize_keywords（追加/削除/置換）、organize_rate（お気に入り/却下/クリア）、または organize_roles を実行する — それぞれ _organized コピーを書き込む。history はファイルのフォルダに対するすべての記録された操作をリストする。undo は最後のn個の出力をジャーナルの undone/ フォルダに移動する（決して削除せず、ファイルが変更されている場合は拒否する）。 |
find | 「あのシーンはどこ？」のルーター。find_shots は、発言内容（文字起こし）、ログ内容（名前、キーワード、ノート、マーカー、オーディオイベント）、そして [find] エクストラとダウンロードしたローカルモデルがあればフレームの見た目に基づいてモーメントをランク付けする — 最初の行はどの階層が回答し、なぜ回答できなかったかを示す。find_index はシーンとキャプションをウォームアップし、どのクリップに文字起こしがないかを報告する（文字起こしは行わず、オンラインにもしない）。find_to_timeline はヒットを多様性スコア付きの _found 選択リールに組み立てる。 |
すべての呼び出しは {"action": "...", "args": {...}} の形式を取ります。グループが所有していないアクションを渡すと、エラーが有効なアクションをリストするので、推測するよりもそれを読んでください。
あなたを困らせるFCPXMLの事実
- 時間は有理数であり、決して浮動小数点数ではない。
3600/2400sは1.5秒です。タイムコードで浮動小数点演算をしたり、自分で丸めたりしないでください。 offsetはタイムライン上の位置。startはソースのイン点。 これらは異なる数値であり、混同すると編集が静かにずれます。- ライブラリクリップとタイムラインクリップは異なる要素。
<asset-clip>はライブラリにあり、<clip>はタイムラインにあります。 - マーカーはクリップの子要素であり、兄弟要素ではない。
<spine>はプライマリ・ストーリーライン。 接続クリップはスパインクリップにレーンでぶら下がります：正は上（ビデオ）、負は下（オーディオ）。.fcpxmldバンドルはディレクトリ であり、Info.fcpxmlとサイドカーデータをラップします。サイドカーは保存時に保持しなければ、オブジェクトトラッキングやシネマティックデータが破壊されます。- クリップ名の重複は一般的。 ツールが両方提供する場合は、名前検索よりも要素ベースの操作を優先してください。
無音除去：適切なものを選ぶ
検出→修正のペアが2つあり、互換性はありません。どちらもこのサーバーの他のすべての検出/修正ペアと同じ分割に従います：検出器は diagnose に、修正器は edit にあります。
detect_media_silence（diagnose）→remove_media_silence（edit）はffmpegで実際のソースオーディオを読み取ります。正確で、遅く、ffmpegのインストールが必要です。detect_silence_candidates（diagnose）→remove_silence_candidates（edit）はタイムラインヒューリスティックのみを使用します。高速で、ffmpeg不要、推測です。
正確さが重要な場合はメディア版を使用してください。どちらを使ったかを必ず伝えてください。
概ね成り立つ作業順序
inspect→diagnose→preview://リソースを読む。- 編集が対話中心なら、
transcriptでアクションtranscript_pack— 発言すべてを1ページにまとめ、計画をクリップ名ではなく言葉から立てる。 generateでアセンブリ、editで微調整、markでチャプター。- 変更した範囲に対して
previewでアクションpreview_checkを、編集が完了したと提示する前に実行する。これが編集を非盲目的にするものです。preview://リソースとpreview_timelineはどちらもXMLから描画します — これらは書かれた内容を示すので、修正されたカットと壊れたカットを区別できません。preview_checkはメディアを読み取ります。一方を他方の代わりに使わず、ツールの呼び出しが成功を報告したからといってスキップしないでください。 deliver、書き出しまたは動作中のアプリへのpush_to_fcp。watchでアクションwatch_startをセッションごとに1回、その後オペレーターが書き出したらwatch_pullを実行する。Final Cut Proにはプログラムによる書き出し機能がありません — Appleは一度も出荷していません — そのため、ループが閉じるのはオペレーターがCmd-Eを押したときだけです。沈黙して待つよりは、そのことをはっきり伝えてください。
やってはいけないこと
- 診断パスなしで編集しないでください。フラッシュフレームとギャップが蓄積します。
- ffmpegやWhisperがインストールされていると想定しないでください。どちらも優雅に劣化し、エラーではなく空の結果を返すので、レスポンスを確認してください。
preview_renderの要約を「UNVERIFIED」という単語を過ぎて読まないでください。これはレンダリングされたファイルの長さが読み戻せなかったことを意味し、そのレンダリングについては何も確認されていません。Substituted:の行を無視しないでください。プロキシレンダリングはトランジションをハードカットとしてレンダリングするため、タイムライン上のディゾルブはあなたが見ているものと異なります。push_to_fcpが呼び出され成功を報告しない限り、編集がFinal Cut Proに届いたと主張しないでください。.fcpxmlファイルを書き出すこととそれをインポートすることは同じではありません。- ツール自身の成功メッセージを、タイムラインが正しく見えることの証明として信頼しないでください。
preview://を読んで確認してください。