FilmCraft — 代理操作
FilmCraft 是一款原生 Rust 影片編輯器（Premiere Pro 等級），其代理介面內建於核心：每個動作都是一個帶有 ID 的指令。選單、快捷鍵、面板、時間軸手勢、CLI、控制頻道、MCP 伺服器以及圖形介面都驅動同一個引擎。已在 0.10.0–0.13.0 版本上於 Windows 和 Linux 驗證。
機器與環境路徑
| 平台 | 執行檔 | 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以及髒旗標。一個序列是作用中的；指令會對其操作。 - 序列具有
video[]與audio[]軌道陣列，每個軌道為{id, name, items[], transitions[], muted, locked, ...}。剪輯為{clip, item, name, start, duration, startFrame, durationFrames, sourceIn, sourceOut, speed, reverse, enabled, link, gainDb, effects[]}——所有時間以滴答表示。 - 放置一段影片會建立兩個連結的剪輯（視訊 + 音訊），具有不同的 id，且
link互相指向對方。預設情況下選取一個會同時選取兩個。 - 時間為整數滴答，每秒 254,016,000,000 個滴答（也是 48000×5292）。
seconds與frame會對齊到影格網格；frame與timecode（例如"00:00:02:12"或;表示掉影格）會精確對應。當需要精確剪切時，優先使用frame。 - 指令為
{"id": "timeline.razor", "params": {...}}。command_list可找出 id 與參數文件；command_run可執行一個（可復原）；command_batch可執行多個。無效的參數型別與未知指令會失敗；未知的參數名稱則會靜默忽略（參閱陷阱）。 - 透過回讀驗證（
sequence_inspect、project_inspect、captions.list、media.status、jobs.list）或透過渲染（render_frame、file.exportFrame）。null結果表示「已執行」，而非「如你所願」。
兩種連線模式
| 模式 | 啟動方式 | 用途 |
|---|---|---|
| 無頭模式 | 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 | 執行一個 {id, params} |
command_batch | 執行 {steps:[{id,params}], stop_on_error} → {completed, failed, results} |
doc_inspect | 一次呼叫取得專案樹 + 作用中序列 |
project_inspect | 樹狀結構、項目、作用中序列、髒旗標 |
sequence_inspect | 作用中序列：設定、軌道、剪輯、轉場、標記 |
media_import | 以絕對路徑匯入檔案（paths、bin、image_sequence） |
render_frame | 在 seconds（或播放頭）處的 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（48 KB JSON：專案 + 序列）以及 filmcraft://commands（192 KB 目錄）。無提示詞。
標準工作流程
- 探查。
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（這可捕捉到回讀無法顯示的錯誤剪輯、黑畫面與缺失轉場）。 - 匯出。
file.exportMedia搭配wait:true（檢查offlineMedia與寫出的檔案）；使用file.exportInterchange進行 NLE 往返。 - 儲存。
file.saveAs（會建立目錄？不會——父目錄必須存在）；然後重新讀取project_inspect.dirty（儲存後為 false）。
尋找指令
command_list {filter:"razor"} 會比對 id、標籤、選單與參數。filmcraft-cli commands razor、describe <id> 與 filmcraft-cli inspect 在 shell 中執行相同功能。所有 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 會出錯。在任何開啟/新建操作後，重新讀取sequence_inspect。- 轉場不在剪輯上。 它們位於
sequence_inspect.video[i].transitions[]中，格式為{id, effect, from, to, start, duration, align, reverse, params}。sequence.removeTransition {transitions:[id]}；sequence.setTransition可編輯持續時間/對齊/參數。 - 字幕不在
sequence_inspect中。 請使用captions.list；提示帶有id, start, end, text。captions.newTrack對於任何未知格式字串會靜默回退到Subtitle。 - 切勿將目錄傳遞給
file.exportMedia。 它會無限掛起（已重現兩次，>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（退格鍵）會留下空隙；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是工作階段範圍的——它在兩個--data-dir工作階段之間不會持久儲存。請使用 GUI 進行持久偏好設定。 - MCP 工具引數要求嚴格（未知鍵 → JSON-RPC
-32602；錯誤型別 →isError伴隨反序列化訊息），但command_run.params會原封不動地傳遞。
參考資料對應表
| 檔案 | 內容 |
|---|---|
references/recipes.md | 已驗證的 JSON：建構、裁切、特效、調色、字幕、圖形、代理、多機位、TTS、匯出、GUI |
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。