Metadata-Version: 2.4
Name: final-cut-pro-cli
Version: 0.1.0
Summary: Agent-friendly CLI for Apple Final Cut Pro on macOS
Project-URL: Homepage, https://github.com/poechant/final-cut-pro-cli
Project-URL: Repository, https://github.com/poechant/final-cut-pro-cli
Project-URL: Issues, https://github.com/poechant/final-cut-pro-cli/issues
Author-email: 钟超 <zhongchao.ustc@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agent,cli,fcp,fcpxml,final-cut-pro,mcp,video-editing
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.10
Requires-Dist: jsonschema>=4.21.0
Requires-Dist: lxml>=5.0
Requires-Dist: mcp>=1.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# final-cut-pro-cli

> Agent-friendly CLI for Apple Final Cut Pro on macOS.

为 Final Cut Pro 提供一个 **可被 Agent / 脚本调用** 的命令行接口，让 Cursor / Claude Code / 自研 Agent 能完成剪辑准备链路（Library / Event / Project / Media / Timeline），并把结果打开到 FCP 中继续人工或后续自动化处理。

## 定位

- **目标用户**：专业剪辑师（脚本化批处理）、自动化 / AI 剪辑工程师
- **核心场景**：辅助专业剪辑工作流。把 FCP 的能力 **原子化、可组合、可调用**
- **不做什么**：不内置 AI 能力（AI 在调用方）；不替代 FCP UI

## 平台限制

| 项 | 要求 |
|----|------|
| 操作系统 | macOS only |
| Final Cut Pro | 10.7+ |
| FCPXML schema | 1.11+ |
| Python | 3.10+ |

启动时会自动检测，不满足条件直接 `PLATFORM_UNSUPPORTED` / `FCP_NOT_INSTALLED` / `FCP_VERSION_TOO_OLD` 退出。

## 安装

```bash
pip install final-cut-pro-cli
```

## 命令面（v0.1 MVP）

### Library 层（FCP 专属，dr-cli 无对应）

```bash
fcp library new <name> [--path <dir>]      # 创建 .fcpbundle 并注册
fcp library list                            # 列出已注册 Library
fcp library open <name|path>                # 在 FCP 中打开
```

### Event 层（FCP 专属）

```bash
fcp event new <name> --library <ref>
fcp event list --library <ref>
```

### Project 层（与 dr-cli 对齐）

```bash
fcp project new <name> --library <ref> --event <ref> [--resolution 1920x1080] [--fps 30]
fcp project list --library <ref> [--event <ref>]
fcp project info <name> --library <ref> --event <ref>
```

### Media

```bash
fcp media import <video>... --library <ref> --event <ref>
```

### Clip 编辑

```bash
fcp clip add --library <ref> --event <ref> --project <name> --asset <asset-id> [--duration <dur>]
fcp clip cut --library <ref> --event <ref> --project <name> --at <timecode>
fcp clip move --library <ref> --event <ref> --project <name> --clip <index> --to <timecode>
fcp clip trim --library <ref> --event <ref> --project <name> --clip <index> --start <tc> --end <tc>
fcp clip delete --library <ref> --event <ref> --project <name> --clip <index>
```

### Subtitle（预留命令面）

```bash
fcp subtitle add <text> --at <tc> --duration <dur>
fcp subtitle import <srt-file>
```

> v0.1 仅保留 subtitle 命令组占位，暂不写入字幕 / 标题内容。完整 subtitle/title
> 能力进入后续版本。

### Export

```bash
fcp export submit <project-name> --preset <name> --output <path>
```

> v0.1 说明：FCP 11.1.1 的 scripting dictionary 没有 `export` / `share` / `render`
> 命令。`fcp export submit` 保留与 dr-cli 对齐的命令面，但会返回结构化
> `export_unavailable` 错误，不使用 UI scripting 伪装导出。MP4 导出暂由 FCP UI
> 手动完成，或在后续版本研究 Compressor / 外部渲染链路。`export status` 是后续
> 异步导出能力的预留命令，v0.1 不实现。

### MCP server 模式

```bash
fcp mcp serve            # 启动 stdio MCP server，供 Cursor / Claude Code 调用
```

示例配置：

- Cursor: [examples/cursor-mcp.json](examples/cursor-mcp.json)
- Claude Desktop: [examples/claude-desktop-mcp.json](examples/claude-desktop-mcp.json)

MCP tool 命名使用点号分组，例如 `library.new`、`event.list`、`project.info`、
`clip.cut`、`export.submit`。工具内部复用同一套 CLI 命令路径，并默认使用
`--json`，因此 MCP 返回值与 shell 调用保持一致。

## 全局选项

- `--json` — 所有命令支持结构化输出（错误也是 JSON）
- `--verbose` — 打印 FCPXML 详细变更和 AppleScript 调用

`--library` / `--event` / `--project` 是具体命令的作用域参数，不是全局参数。v0.1
不会读取 FCP 当前 active library，Agent 调用时应显式传入目标 Library / Event /
Project。

## 与 davinci-resolve-cli 的对齐策略

| 命令层 | 是否对齐 dr-cli | 说明 |
|--------|----------------|------|
| Library | ❌ 不对齐 | dr-cli 无 Library 概念，fcp-cli 独有 |
| Event | ❌ 不对齐 | dr-cli 无 Event 概念，fcp-cli 独有 |
| Project / Media / Clip / Export | ✅ **尽量对齐** | 在 FCP 需要额外补充 Library / Event 作用域 |
| Subtitle | 🚧 预留 | v0.1 仅保留命令组，占位对齐后续版本 |

详见 [docs/dr-cli-alignment.md](docs/dr-cli-alignment.md)。

## 错误码

退出码分段：

| 范围 | 含义 |
|------|------|
| 0 | 成功 |
| 1-19 | 用户输入错误（参数非法、文件不存在） |
| 20-39 | FCP 状态错误（FCP 未运行、Library 未打开） |
| 40-59 | 长时操作错误（AppleScript timeout、后续导出/渲染失败） |
| 60+ | 内部错误（fcpxml 解析失败、AppleScript 异常） |

详见 [docs/error-codes.md](docs/error-codes.md)。

## 架构

src-layout，与 davinci-resolve-cli 在目录布局、模块命名、命令组织上一一对应：

```
src/fcp/
├── cli.py              ← 入口 main_entry()，Typer
├── bootstrap.py        ← 平台/FCP 版本预检（macOS + 10.7+）
├── errors.py           ← 错误码段位 + FcpCliError
├── output.py           ← --json / rich 双输出
├── timecode.py         ← 时间码解析（与 dr-cli 同语义）
├── fcp_app.py          ← AppleScript 桥接（对应 dr-cli/resolve.py）
├── fcpxml/             ← FCPXML 读写（fcp 独有，主路径）
├── commands/
│   ├── library.py      ★ fcp 独有
│   ├── event.py        ★ fcp 独有
│   ├── project.py      ↔ dr-cli/project.py
│   ├── media.py        ↔ dr-cli/media.py
│   ├── timeline.py     ↔ dr-cli/timeline.py
│   ├── subtitle.py     ↔ (dr-cli v0.3 计划)
│   ├── export.py       ↔ dr-cli/render.py（FCP 叫 Export，参数 1:1）
│   ├── doctor.py       ↔ dr-cli/doctor.py
│   ├── completion.py   ↔ dr-cli/completion.py
│   └── mcp_cmd.py      ↔ dr-cli/mcp_cmd.py
├── jobs/               ← async 任务（预留给后续 export / MCP 长任务）
├── mcp/                ← MCP server 实现
└── schemas/            ← *.json，与 dr-cli/schemas/ 字段命名一致（camelCase）
```

### 设计约束

- **FCPXML 主路径** — 所有内容编辑（library/event/project/media/clip/subtitle）走 FCPXML 文件操作，不依赖 FCP 运行
- **AppleScript 仅做运行时触发** — v0.1 只实现 `library open`（标准 application `open` 命令）与 FCP library inspection；FCP scripting dictionary 当前没有 export/share 自动化能力
- **禁止 UI scripting** — 不使用 System Events、坐标点击、key code、keystroke、AXUIElement；测试会扫描并拒绝这些片段

## 开发

```bash
# 安装开发依赖
pip install -e ".[dev]"

# 单元测试
pytest tests/fcpxml tests/cli

# 端到端测试（需要 macOS + FCP 10.7+）
FCP_E2E_OPEN_REAL_FCP=1 \
PYTHONPATH=/private/tmp/fcp-cli-pytest-stubs:src \
pytest tests/e2e/test_real_fcp_open.py -m integration -q
```

测试用例清单见 [test-cases.md](test-cases.md)。
E2E 排障见 [docs/e2e-troubleshooting.md](docs/e2e-troubleshooting.md)。

## 路线图

- **v0.1**（M1，当前）— 剪辑准备闭环 MVP：library/event/project/media import/clip add/cut/library open + `export_unavailable` 明确降级 + MCP server
- **v0.2** — 对齐 dr-cli v0.2：跨平台（FCPXML 操作部分）、recipe 模式、批量素材 glob/import 辅助
- **v0.3** — 对齐 dr-cli v0.3：razor-cut 增强、MCP HTTP、subtitle 完整支持、config 文件

## 姊妹项目

- [davinci-resolve-cli](https://github.com/poechant/davinci-resolve-cli) — 同团队，DaVinci Resolve 的 CLI（Project 层及以下命令面对齐）

## License

MIT
