filmcraft 是做什麼的？
更新： 如果此資料夾有
.installed-from檔案（在從 repo 複製時寫入），請在每個工作階段執行一次git ls-remote https://gitlab.com/e1dred/agent-skills.git HEAD。取輸出中以HEAD結尾的那一行雜湊值；若與檔案中的不同，告知使用者有較新版本並提供更新選項（請參閱 https://gitlab.com/e1dred/agent-skills/-/blob/main/INSTALL.md 中的「更新」章節，該章節可合併本地編輯）；未經詢問絕不更新。比較雜湊值前請先去除前後空白。若無檔案、為 clone 或符號連結、或無網路（git ls-remote輸出為空或發生錯誤），則跳過不處理。
來自首次 headless 任務的現場筆記，最後測試於 FilmCraft 0.17.1（Linux AppImage）。FilmCraft 是一個
早期 Alpha 版、以 Rust 撰寫的 Premiere 風格影片編輯器。每個選單項目與按鈕都是一個引擎命令；CLI、
MCP 伺服器與應用程式的控制通道執行相同的命令。如果 filmcraft-cli --version 較新，請在依賴此處內容前重新確認。
設定
- CLI： 從 AppImage 中提取（
filmcraft.appimage --appimage-extract，將usr/bin/filmcraft-cli複製到某個穩定位置）；獨立執行，無視窗。切勿對 AppImage 本身執行--version。 - Headless：
filmcraft-cli --project p.fcproj exec <id> key=value …；腳本為 JSON lines 格式並保持同一個工作階段：filmcraft-cli --project p.fcproj run script.jsonl [--save]，其中每一行格式為{"id":"…","params":{…}}， 或在使用file.newProject後獨立執行filmcraft-cli run。子命令：commands、describe、inspect、import、export、render、probe。 - 即時應用程式：
filmcraft --control 9876（或設定FILMCRAFT_CONTROL_PORT）；監聽器需要在環境變數中設定FILMCRAFT_CONTROL_TOKEN（64 個十六進位字元）——若無則保持關閉。使用filmcraft-cli mcp --bridge 127.0.0.1:9876橋接。 - MCP：
filmcraft-cli mcp（headless）或--bridge（即時）。
檔案位置
閱讀與任務相符的檔案；每個檔案列出其包含的章節。使用 grep -n 搜尋 reference/ 以尋找命令 ID。
reference/ 中的檔案 | 閱讀時機 | 章節 |
|---|---|---|
projects-and-timeline.md | 專案、匯入媒體、序列、播放頭、剃刀與修剪、標記、儲存、轉場、影片效果與關鍵影格、影格凍結、專案筆記 | 專案與媒體；序列；裁切與修剪；標記與儲存；轉場；影片效果與關鍵影格；影格凍結、選取與專案筆記；其他編輯工具 |
titles-and-graphics.md | 文字與形狀圖層、小影格的尺寸/調整、讀取圖層、垂直文字與匯入的圖片 | 標題；尺寸與調整；圖層屬性；其他圖層工具 |
audio-mixer.md | 混音器通道、數值、子混音、插入與傳送；片段增益與 Essential Sound | 混音器；片段音訊 |
captions.md | 字幕軌、新增/編輯/移動字幕、SRT 匯入與匯出 | 字幕軌與 SRT |
export.md | 匯出預設與格式、匯出佇列、MP4/GIF 匯出、影格靜止畫面、交換格式匯出、探測 | 預設；匯出；預設與匯出佇列；靜止畫面；探測 |
command-catalogue.md | 依功能分類的所有其他命令 ID（clip、timeline、sequence、trim、graphics、edit、file、project、multicam、source、prefs、shortcuts…），每個標示為已驗證（JSON 路徑舊→新）、有回傳結果、已執行、或因某些原因被拒絕；解鎖依賴選取狀態的命令所需的設定 | 每個功能一個章節 |
live-app.md | 透過 --bridge 驅動執行中的應用程式：ui_* 工具、僅即時模式可用的功能、在隱藏顯示器上執行 | 連線；即時應用程式的額外功能 |
newer-commands.md | 每個版本新增或變更的內容 | 0.17.0；0.17.1 |
log.md | 各項功能測試時間的日期記錄 | 記錄 |
CLI 基本操作（已驗證）
filmcraft-cli commands --json # 716 個命令：id、label、menu、params、enabled
filmcraft-cli describe file.import # 單一命令的參數說明
filmcraft-cli --project p.fcproj inspect # 回傳 {project:{…}, sequence:{…}} JSON
filmcraft-cli import clip.mp4 --project p.fcproj
filmcraft-cli --project p.fcproj export out.mp4 --scale 0.5 --quality 70
filmcraft-cli --project p.fcproj render --seconds 2 --out frame.png
filmcraft-cli probe clip.mp4 # kind、duration（ticks）、視訊/音訊串流詳細資訊
- JSONL 腳本會保持狀態：
file.newProject→file.import {"paths":["clip.mp4"]}→{"items":[1]}→file.newSequenceFromClip {"items":[1]}→{"clips":[6,7],"sequence":4}→ … →file.saveAs {"path":"p.fcproj"}。 - 每次後續 CLI 呼叫都需傳入
--project：否則每次呼叫都是全新工作階段。
陷阱
- 時間單位是 ticks，而非影格： 序列回報 762,048,000,000 代表 3 秒（254,016,000,000 ticks/秒）；
playhead.set接受seconds、frame、time或timecode，並對齊到最近的影格（1.5 秒 → 影格 37）。 - 預設大小的文字圖層會超出小影格。
graphics.newText預設為 100 px：在 320×180 的序列中，size:48的 "Hello FilmCraft" 從 x=40 開始繪製，寬度達 334.7 px，右側被裁切。可設定size（約 32 → 223 px 寬；已透過渲染確認）。段落文字搭配box:[w,h]會自動換行，但方框會裁切超出其高度的行：box:[240,60]搭配 size 40 只顯示 "Hello"（第二行被切斷），因此方框高度要足夠容納每一行（約每行 1.3 × size）。 - 跨越同步鎖定軌道的漣波編輯會失敗： 當標題位於 V2 時，
timeline.trim搭配mode:"ripple"會回應「此編輯會破壞同步：V2 已同步鎖定且有一個片段擋路」。請先鎖定/解鎖另一軌道，或使用非漣波方式修剪。 probe --image-sequence只能接受編號的靜止畫面；用於影片時會報錯。- Headless 模式下
effects.addKeyframe搭配原始mediaTime無效（回傳{added:false, mediaTime:0}；0.17.0），但在即時應用程式中，{clip, effect:"opacity", param:"opacity", seconds:1.5, value:40}可新增關鍵影格（關鍵影格從 5 變為 6；時間會對齊到影格：624699432000）。Headless 模式下，請移動播放頭並使用effects.toggleAnimation，或對標題屬性使用graphics.set {…,"keyframe":true}。 mixer.addInsert需要真實的音訊效果 ID（例如hard_limiter，來自effects.list {"kind":"Audio"}），而非如volume的標籤；mixer.addSend需要同一執行中mixer.addSubmix回傳的子混音ref。graphics.*命令需要在同一個工作階段中有標題： 先在相同腳本中執行graphics.newText，然後graphics.alignFrame.*、nudge*、fontSize*、leading*才能在 headless 模式運作（讀取graphics.list {clip}→layers[0]）。若無標題，則回應「無圖形片段」。graphics.deleteLayer僅在即時模式下被接受（無回讀）。- 選取狀態不會在儲存/重新開啟後保留： 請將
project.select {items:[id]}/timeline.select放在需要選取狀態的命令前（例如「請在專案面板中選取一個項目」、「未選取任何片段」）。 - FCPXML 匯出可能遺失標題：
file.exportInterchange {"format":"fcpxml"}報告圖形片段「不支援」但仍寫入檔案；在信任交換格式匯出前，請先閱讀報告。 --demo會開啟內建示範專案：可檢查與渲染（1 秒處的 1920×1080 影格），匯出僅測試至正常；除非--allow-offline接受，否則遺失媒體會匯出為佔位影格。file.exportMedia會等待檔案寫入完成，除非設定"wait":false；CLI 的export永遠會等待。
回報前請先驗證
使用 inspect sequence（片段開始/結束影格、軌道、轉場、效果）、probe 檢查匯出檔案的長度與編解碼器，以及 render 渲染感興趣時間點的影格來檢查。影格計數：25 fps 的 3 秒 = 75 個影格；一次 -10 影格的漣波修剪後變為 65 個影格。