filmcraft 是做什么的？
更新： 如果此文件夹包含一个
.installed-from文件（在从仓库复制时写入），请在每个会话期间运行一次git ls-remote https://gitlab.com/e1dred/agent-skills.git HEAD。取输出行中以HEAD结尾的哈希值；如果它与文件中的哈希值不同，请告知用户存在较新版本并提供更新选项（请参阅 https://gitlab.com/e1dred/agent-skills/-/blob/main/INSTALL.md 中的“更新”部分，该部分可合并本地编辑）；未经询问切勿更新。比较哈希值前请先去除空白。如果没有文件、是克隆或符号链接、或者无网络连接（git ls-remote输出为空或报错）：则静默跳过。
来自首次无头任务的田野笔记，最后测试于 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。 - 无头模式：
filmcraft-cli --project p.fcproj exec <id> key=value …；脚本为 JSON 行格式并保持单个会话：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（无头模式）或--bridge（实时模式）。
文件内容索引
读取与任务匹配的文件；每个文件列出了其所包含的章节。使用 reference/ 中的 grep -n 查找命令 ID。
reference/ 中的文件 | 阅读目的 | 章节 |
|---|---|---|
projects-and-timeline.md | 项目、导入媒体、序列、播放头、剃刀和修剪、标记、保存、转场、视频效果和关键帧、帧保持、项目备注 | 项目和媒体；序列；裁剪和修剪；标记和保存；转场；视频效果和关键帧；帧保持、选择和项目备注；其他编辑工具 |
titles-and-graphics.md | 文本和形状图层、小型帧上的尺寸/适配、回读图层、垂直文本和导入的图像 | 标题；尺寸和适配；图层属性；其他图层工具 |
audio-mixer.md | 混音器条、值、子混音、插入和发送；剪辑增益和基本声音 | 混音器；剪辑音频 |
captions.md | 字幕轨道、添加/编辑/移动字幕、SRT 导入和导出 | 字幕轨道和 SRT |
export.md | 导出预设和格式、导出队列、MP4/GIF 导出、静态帧、互换格式导出、探测 | 预设；导出；预设和导出队列；静态帧；探测 |
command-catalogue.md | 所有其他按族分类的命令 ID（剪辑、时间线、序列、修剪、图形、编辑、文件、项目、多机位、源、偏好设置、快捷键等），每个都标记为已验证（JSON 路径 旧→新）、返回了结果、已运行、或被拒绝并说明原因；使依赖于选择的命令可用的设置 | 每个族一个章节 |
live-app.md | 通过 --bridge 驱动正在运行的应用：ui_* 工具、仅限实时应用的功能、在隐藏显示器上运行 | 连接；实时应用的附加功能 |
newer-commands.md | 每个版本添加或更改的内容 | 0.17.0；0.17.1 |
log.md | 带有日期的测试记录 | 日志 |
CLI 要点（已验证）
filmcraft-cli commands --json # 716 个命令：id、标签、菜单、参数、启用状态
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 # 种类、时长（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，而非帧： 序列报告 3 秒为 762,048,000,000（每秒 254,016,000,000 ticks）；
playhead.set接受seconds、frame、time或timecode并 吸附到最近的帧（1.5 秒 → 第 37 帧）。 - 默认大小的文本图层会溢出小尺寸帧。
graphics.newText默认为 100px：在 320×180 的序列上， "Hello FilmCraft" 在size:48时从 x=40 绘制出 334.7px 宽，并在右边缘被截断。通过设置size（约 32 → 223px 宽；已在渲染中检查）来适配。带box:[w,h]的段落文本会换行，但该框 会裁剪不适合其高度的行：box:[240,60]在 size 40 时仅显示 "Hello"（第二行被截断）， 因此请确保框的高度足以容纳每一行（每行约 1.3 × size）。 - 波纹编辑在同步锁定轨道上失败： 当 V2 轨道上有一个标题时，
timeline.trim在mode:"ripple"时回复 “此编辑会破坏同步：V2 已同步锁定且中间有一个剪辑”。首先锁定/解锁其他轨道，或者在不使用波纹的情况下 进行修剪。 probe --image-sequence仅接受编号的静态图像；对影片使用会报错。- 在无头模式下使用原始
mediaTime的effects.addKeyframe不生效（{added:false, mediaTime:0}；0.17.0），但在 实时应用中，{clip, effect:"opacity", param:"opacity", seconds:1.5, value:40}成功添加了一个（关键帧 5 → 6；时间 吸附到帧：624699432000）。在无头模式下，移动播放头并使用effects.toggleAnimation，或对标题属性使用graphics.set {…,"keyframe":true}。 mixer.addInsert需要一个真实的音频效果 ID（例如从effects.list {"kind":"Audio"}得到的hard_limiter），而不是 诸如volume之类的标签；mixer.addSend需要来自同一运行中mixer.addSubmix的子混音ref。graphics.*命令在同一会话中需要有一个标题： 先在同一脚本中运行graphics.newText，然后graphics.alignFrame.*、nudge*、fontSize*、leading*才能在无头模式下工作（读取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 一帧以进行查看。帧计数：3 秒 @ 25 fps = 75 帧；一次 -10 帧的波纹修剪
得到 65 帧。