FilmCraft — エージェント操作ガイド
FilmCraftはネイティブRust製のビデオエディタ（Premiere Proクラス）で、エージェントインターフェースがビルトインされています。すべての操作はidを持つコマンドとして実装されています。メニュー、ショートカット、パネル、タイムライン操作、CLI、制御チャンネル、MCPサーバー、GUIはすべて同じエンジンを駆動します。WindowsおよびLinuxで0.10.0～0.13.0で検証済みです。
マシンおよび環境パス
| プラットフォーム | バイナリ | CLI | デフォルトデータディレクトリ |
|---|---|---|---|
| Windows | C:\Program Files\FilmCraft\filmcraft.exe | C:\Program Files\FilmCraft\filmcraft-cli.exe | %LOCALAPPDATA%\FilmCraft |
| Linux | /usr/bin/filmcraft | /usr/bin/filmcraft-cli | ~/.local/share/filmcraft |
| macOS | /Applications/FilmCraft.app/Contents/MacOS/filmcraft | filmcraft-cli（~/.local/binまたはPATH内） | ~/Library/Application Support/filmcraft |
- ログの場所:
<data-dir>/Logs/filmcraft.log - 制御ポート: ループバックのみ（
--control <port>またはFILMCRAFT_CONTROL_PORT、例：9876、7991、50051） - コマンド数: 42の名前空間に710個
- エフェクト: 130種類のビデオエフェクト、112種類のビデオトランジション、3種類のオーディオトランジション
メンタルモデル
- プロジェクト（
.fcproj、JSON）はビンとアイテムを保持します：Movie、Audio、Image、Sequence、Multi-Camera Source Sequence。project_inspectはツリー、activeSequence、ダーティフラグを返します。アクティブなシーケンスは1つだけです。コマンドはそのアクティブなシーケンスに対して作用します。 - シーケンスには
video[]とaudio[]のトラック配列があり、各トラックは{id, name, items[], transitions[], muted, locked, ...}です。クリップは{clip, item, name, start, duration, startFrame, durationFrames, sourceIn, sourceOut, speed, reverse, enabled, link, gainDb, effects[]}で構成されます。すべての時間はティック単位です。 - ムービーの配置では、2つのリンクされたクリップ（ビデオ＋オーディオ）が作成され、それぞれ異なるidを持ち、
linkが互いを指します。デフォルトではどちらかを選択すると両方が選択されます。 - 時間は整数ティックで、1秒あたり254,016,000,000（48000×5292でもあります）。
secondsとframeはフレームグリッドにスナップされます。frameとtimecode（例："00:00:02:12"、ドロップフレームの場合は;）は正確にマッピングされます。正確なカットが必要な場合はframeを優先してください。 - コマンドは
{"id": "timeline.razor", "params": {...}}の形式です。command_listでidとパラメータのドキュメントを検索できます。command_runで1つ実行（元に戻せます）。command_batchで複数実行できます。不正なパラメータ型や未知のコマンドは失敗します。未知のパラメータ名は静かに無視されます（「落とし穴」を参照）。 - 状態を読み戻して検証してください（
sequence_inspect、project_inspect、captions.list、media.status、jobs.list）、またはレンダリング（render_frame、file.exportFrame）で確認してください。nullの結果は「実行した」を意味し、「意図した通りに動いた」を意味しません。
2つの接続モード
| モード | 開始方法 | 用途 |
|---|---|---|
| ヘッドレス | filmcraft-cli mcp（--demo、--project p.fcproj、--data-dir d） | ウィンドウなし、バッチビルド、書き出し、スクリプト |
| アプリブリッジ | filmcraft --control 50051 + filmcraft-cli mcp --bridge 127.0.0.1:50051 | 実際のウィンドウ：UI状態、スクリーンショット、クリック、キー操作、ドラッグ、GUI専用コマンド |
ユーザーリクエストに応じてFilmCraftを起動（「起動して」/「start FilmCraft」）
ユーザーがFilmCraftの起動を依頼した場合（「FilmCraftを起動して」「立ち上げて」「開いて」「start FilmCraft」）：
- 既に起動しているか確認：
- Windows：
Get-Process filmcraft -ErrorAction SilentlyContinue - Linux / macOS：
pgrep filmcraft - 起動している場合、制御ポートが応答するか確認する（
filmcraft-cli --bridge 127.0.0.1:50051 inspect）。 - 制御ポートなしで起動している場合、ユーザーに通知：「FilmCraftは現在制御ポートなしで起動しています。作業内容を保存して再起動するか、
--control 50051を付けて閉じてから再起動することを許可してください。」
- Windows：
--control <port>（デフォルト：50051）と64文字のFILMCRAFT_CONTROL_TOKENを指定して起動：- Windows（PowerShell）—
scripts/launch.ps1を使用して、WinSta0\Default上にデスクトップウィンドウが表示されるようにする：
（これにより自動的にpowershell -File scripts/launch.ps1 -Port 50051FILMCRAFT_CONTROL_TOKENが設定・保持され、ポートが構成され、対話型タスクとして起動されるため、GUIがバックグラウンドセッションに隠れずログインユーザーに表示されます。） - Linux：
./scripts/launch.sh 50051 - macOS：
./scripts/launch.sh 50051
- Windows（PowerShell）—
- 接続を確認：
- 1～3秒待ってから
filmcraft-cli --bridge 127.0.0.1:50051 inspectを実行。 - 応答があれば、FilmCraftがアクティブでポート50051で待機中であり、ライブタイムライン編集や協調コマンドの準備ができていることを報告する。
- 1～3秒待ってから
17のMCPツール
| ツール | 目的 |
|---|---|
command_list | すべてのコマンド（filter、enabled_only） |
command_run | 1つの {id, params} を実行 |
command_batch | {steps:[{id,params}], stop_on_error} を実行 → {completed, failed, results} を返す |
doc_inspect | プロジェクトツリー＋アクティブシーケンスを1回の呼び出しで取得 |
project_inspect | ツリー、アイテム、アクティブシーケンス、ダーティフラグ |
sequence_inspect | アクティブシーケンス：設定、トラック、クリップ、トランジション、マーカー |
media_import | 絶対パスでファイルをインポート（paths、bin、image_sequence） |
render_frame | 指定秒数（またはプレイヘッド位置）でPNG出力、max_side 指定可能 |
render_preview | render_frame と同じ（ブリッジ：プログラムモニター） |
ui_inspect | ウィンドウ/UIの状態（ツール、ワークスペース、選択、ダイアログ、再生、要素数） |
ui_elements | 画面上の要素（id、ラベル、矩形）を prefix 指定で取得 |
ui_click | id または x,y でクリック（button、count、modifiers） |
ui_drag | ポイント間または要素id間で押下→移動→解放（steps） |
ui_key | キーまたはショートカット（Space、Cmd+Z、Shift+Delete） |
ui_type | フォーカスされたフィールドに入力 |
ui_screenshot | ウィンドウ全体または指定 panel のPNG画像 |
ui_control | 任意の制御方法：ui.set、ui.menu.list、ui.playback など |
リソース：filmcraft://document（48KB JSON：プロジェクト＋シーケンス）および
filmcraft://commands（192KB カタログ）。プロンプトはありません。
標準ワークフロー
- 調査。
project_inspect/doc_inspect。ヘッドレスモードでは--demoまたは--projectが指定されていない限り空の状態で開始。ブリッジモードでは最初にui_inspect。 - 構築。
file.newProject→file.import（絶対パス）またはfile.importDemoFootage→file.newSequence→timeline.place。 - カット。
playhead.set+timeline.razor、timeline.trim、timeline.slip、timeline.move、edit.clear/edit.rippleDelete。 - スタイル。
effects.apply+effects.setParam。sequence.applyVideoTransition。lumetri.applyPreset。graphics.newText。markers.add。captions.add。 - 検証。
sequence_inspect/captions.listを読み取り。適切な時点でrender_frameを行い、生成されたPNGを確認（これにより、読み戻しでは検出できない間違ったクリップ、黒フレーム、欠落したトランジションを発見できます）。 - 書き出し。
wait:trueを指定してfile.exportMedia（offlineMediaと書き出されたファイルを確認）。file.exportInterchangeはNLEラウンドトリップ用。 - 保存。
file.saveAs（ディレクトリは自動生成されません — 親ディレクトリが存在する必要があります）。その後project_inspect.dirtyを再読み取り（保存後は false）。
コマンドの検索
command_list {filter:"razor"} はid、ラベル、メニュー、パラメータを検索します。filmcraft-cli commands razor、describe <id>、filmcraft-cli inspect もシェルから同様の操作が可能です。全701個のidとパラメータドキュメントは references/commands.md にあり、検証済みのステップバイステップJSONは references/recipes.md にあります。
まずは以下から始めてください：file.newProject、file.import、file.newSequence、timeline.place、timeline.razor、timeline.trim、timeline.slip、timeline.move、timeline.select、edit.clear、edit.rippleDelete、edit.undo、effects.apply、effects.setParam、sequence.applyVideoTransition、sequence.setTransition、markers.add、captions.newTrack、captions.add、graphics.newText、file.exportMedia、file.exportInterchange、file.exportFrame、file.saveAs。
時間を浪費する落とし穴
- コマンドパラメータは寛容 — 未知のキーや一部の間違った型は静かに無視されます。
timeline.trim {seconds:-1}は{"delta":0}を返します（キーはdeltaです）。timeline.place {seconds:"2"}は0に配置します。fps:"fast"は23.976にフォールバックします。一部のコマンドはバリデーションを行います（graphics.set、markers.add）ので、エラーで不正なパラメータを検出できるとは決して考えないでください。パラメータドキュメントを読み、状態を読み戻してください。 file.newSequenceはアクティブシーケンスを切り替え、{sequence: id}を返します。sequence.openは{item: id}を必要とします —sequenceやクリップidを渡すとエラーになります。open/newの後は必ずsequence_inspectを再読み取りしてください。- トランジションはクリップ上にはありません。 これらは
sequence_inspect.video[i].transitions[]に{id, effect, from, to, start, duration, align, reverse, params}として存在します。sequence.removeTransition {transitions:[id]}で削除。sequence.setTransitionでduration/align/paramsを編集します。 - キャプションは
sequence_inspectに含まれません。captions.listを使用してください。各キューの手がかりはid, start, end, textを持ちます。captions.newTrackは未知のフォーマット文字列に対して静かにSubtitleにフォールバックします。 file.exportMediaにディレクトリを渡さないでください。 無期限にハングします（2回再現、>3分、出力なし）。完全なファイルパスを使用してください。- フォーマットが拡張子より優先されます。
format:"gif"でout.mp4を指定するとout.mp4.gifが書き出されます。ProResでout.mp4を指定するとout.mp4.movが書き出されます。結果のpathが信頼できる情報です。 timeline.placeでdurationがソースより長い場合、警告なしに最後のフレームを保持します。メディアの長さを考慮してトリミングしてください。range:"inOut"でマークがない場合、静かにシーケンス全体を書き出します。range:"custom"+startSeconds/endSecondsが信頼できるサブレンジ指定方法です。jobs.listはツールではなくコマンドです。command_run {id:"jobs.list"}で実行。jobs.cancel {job}で部分ファイルを削除します。wait:falseの書き出しは{job, path, poll, cancel}を返します。- デモフッテージは合成素材です。 デモメディアのインターチェンジ書き出し（FCPXML/AAF/OMF）はクリップを失います。実際のディスク上のメディアではラウンドトリップします（
references/formats-and-roundtrip.mdを参照）。 edit.clear（Backspace）はギャップを残します。edit.rippleDeleteはギャップを閉じます。sequence.lift/extractは選択ではなくシーケンスのイン/アウトマークを必要とします。lumetri.applyPresetは、以前のルックを置き換える代わりに毎回新しいLumetriエフェクトを追加します。古いエフェクトを削除するか、パラメータを直接設定してください。- GUI専用コマンドは
command_listに表示されません：window.workspace.{editing,assembly,color,effects,audio}、window.workspace.reset、window.toggleFullScreen、app.about。これらはブリッジ上にのみ存在します。 - HEVC書き出しはここでは利用できません（「エンコーダーが登録されていません」）。H.264、ProRes、DNxHR、MJPEG、MXF、イメージシーケンス、オーディオはすべて動作します。
- ヘッドレスセッションでの
prefs.setはセッションスコープです — 2つの異なる--data-dirセッション間で永続化されませんでした。永続的な設定にはGUIを使用してください。 - MCPツールの引数は厳格です（未知のキー → JSON-RPC
-32602、間違った型 → デシリアライズメッセージ付きisError）が、command_run.paramsはそのまま通過します。
リファレンスマップ
| ファイル | 内容 |
|---|---|
references/recipes.md | ビルド、カット、エフェクト、カラー、キャプション、グラフィックス、プロキシ、マルチカム、TTS、書き出し、GUIの検証済みJSON |
references/commands.md | 名前空間ごとにグループ化された全701コマンド、パラメータドキュメント付き |
references/mcp-and-control.md | MCP詳細、エラー形状、リソース、制御方法、GUI専用コマンド |
references/cli.md | filmcraft-cli サブコマンド、フラグ、終了コード、オフラインメディア、ヘッドレスジョブ |
references/formats-and-roundtrip.md | 書き出しマトリックス＋独立検証、インターチェンジラウンドトリップ |
references/bugs-and-workarounds.md | 再現されたすべての不具合と最小限の再現手順 |
references/maintenance.md | バージョンの再検証、コマンドのダンプ、このスキルの更新 |
scripts/probe.sh | MCPハンドシェイク＋ツール数＋バージョン |
scripts/dump-commands.sh | コマンドカタログの再生成 |
scripts/smoke-test.sh | ビルド→レンダリング→書き出し→独立検証 |
コミュニティ：https://discord.gg/artcraft · https://getartcraft.com/apps/filmcraft · https://github.com/storytold/filmcraft。