# FCP Teaching Editor MCP

**面向中文教学视频的可审核剪辑工具：本地转写 → 术语校正 → 气口与停顿审核 → 同步字幕 → Final Cut Pro 工程。**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.12+](https://img.shields.io/badge/Python-3.12%2B-3776AB.svg)](pyproject.toml)

FCP Teaching Editor MCP is a review-first editing assistant for Chinese teaching videos. It combines local ASR, auditable edit proposals, frame-based subtitle mapping, and an editable FCPXML handoff. An AI host interprets the lesson; a human authorizes cuts; Final Cut Pro handles final review and movie export.

当前版本 **0.1.0**。这是 Python CLI / MCP 服务与 HTML 审核报告，适合与 Codex、Antigravity 等支持 MCP 的 Agent 配合使用。**它没有独立桌面编辑器，也不自动控制 Final Cut 或直接渲染 MP4。**

## 为什么开发

教学录屏和实验讲解中，气口、口癖、试操作和等待会拖慢节奏，但静音也可能正在展示计数、板书、实验现象或推导步骤。普通“自动删静音”容易删掉教学信息；中文专业词汇识别错误，又会使字幕与公式失真。

本项目把这些决策分开：工具提供原始转写、源时间、关键帧与剪辑候选；Agent结合物理语境校正和解释；用户授权具体修改；最后按同一帧映射生成素材片段和字幕，并到 Final Cut 验证真实导入效果。

典型场景是高中物理实验教学、软件操作演示和单素材中文课程。双缝干涉案例中的条纹计数、双缝间距、屏距和波长公式属于应保护的讲解语境；本项目不采集传感器数据、不测量干涉条纹、不实现计算机视觉实验分析。

## 实际运行截图

以下截图来自公开演示脚本生成的原创示意图与 macOS 中文合成讲解，实际经过本项目的 ASR、审核和导出流程；示意图不是实验测量数据。截图隐藏了本机路径，没有使用私人课程录像。

![实际生成的审核报告](docs/images/review-report.jpg)

*HTML 审核报告显示源帧与最终帧、候选原因、审核状态和源区间。未批准的候选仍保留。*

![实际字幕与时间映射报告](docs/images/subtitle-mapping.jpg)

*源时间与最终时间共用整数帧映射，方便检查切口、字幕和授权。*

![Final Cut Pro 导入演示工程](docs/images/final-cut-handoff.png)

*独立测试资源库中的实际导入工程。Final Cut 的查看和回导是单独验收步骤，不属于 MCP 自动 GUI 控制。*

## 核心功能与特色

| 功能 | 当前实现 |
|---|---|
| 素材检查 | ffprobe 检查流、时长、帧率、音轨、颜色/旋转约束与 SHA256；独立派生音频、六帧联系表 |
| 中文转写 | faster-whisper，CPU int8，实际 word/token spans、segments、识别概率与术语提示 |
| 专业术语校正 | 内置物理词汇与自定义 aliases；连续原始 word IDs、精确 before、after/reason 绑定，保留原时段 |
| 审核候选 | 中文口癖、相邻重复、自我纠正提示、长停顿、语音间隙与声学疑似呼吸，全部默认 pending |
| 紧凑气口 | `compact-teaching-v1`：ASR、校正短句、Silero VAD及可选独立语音跨度并集，向内取整到帧 |
| 教学保护 | 指定源区间保护；讲解默认 1×；气口、实验等待和重复解释须按具体区间审核 |
| 变速 | 指定不重叠源区间 0.25–4×；默认拒绝已识别语音上的非1×变速；记录请求/实际量化速度 |
| 可撤销与审计 | 原片/raw只读；追加修订、journal、checksum、expected revision、undo 创建新修订 |
| 同步导出 | 新目录中的 FCPXML、简体中文原生 iTT Caption 或 Basic Title、SRT、HTML、timeline/manifest |
| 导入比较 | 本机 Apple DTD/结构校验；另存 Final Cut XML后比较时长、片段、速度、字幕与音轨元数据 |

特色是**可复核、保留教学意义、字幕与素材共用映射**，不是识别模型自身能理解全部教学内容。候选 confidence 是未校准启发式评分；ASR token spans不是逐汉字强制对齐。

## 工作原理与技术架构

```mermaid
flowchart LR
    A[本地源视频] --> B[ffprobe 与派生音频和关键帧]
    B --> C[本地中文 ASR]
    C --> D[不可变原始转写]
    D --> E[Agent 术语校正与语境审核]
    B --> F[声学与 VAD 候选]
    E --> G[待审核剪辑计划]
    F --> G
    G --> H[用户授权与保护区]
    H --> I[整数帧时间映射]
    I --> J[FCPXML 与 SRT 与 HTML]
    J --> K[Final Cut 实际导入与独立回导]
```

工具不需要另配付费 LLM API Key。专业语义判断由使用 MCP 的 AI host 完成；本地识别和音视频处理留在本机，但发送给 host 的转写/图像受该 host 的数据政策影响，因此不能把整个工作流称为完全离线。

主要技术：Python 3.12、官方 MCP SDK FastMCP stdio、FFmpeg/ffprobe、faster-whisper/CTranslate2、Silero VAD、NumPy、Pillow、Fraction/整数帧、defusedxml、Apple FCPXML DTD、pytest。

| 模块 | 职责 |
|---|---|
| `media.py` | 媒体真值、格式约束、派生音频/帧、环境诊断 |
| `analysis.py` | 中文 ASR、术语表、初始启发式建议 |
| `rhythm.py` | 语音范围并集、气口缓冲、保护及重复候选过滤 |
| `editing.py` | 校正、提议、审核、变速、保护、撤销 |
| `storage.py` | 文件锁、源完整性、原子指针、不可变修订 |
| `timeline.py` | 源帧到输出帧映射、字幕分句与SRT |
| `export.py` / `verification.py` | FCPXML适配、HTML报告、结构/DTD检查与独立回导比较 |
| `server.py` / `cli.py` | MCP工具、后台分析任务与同一core的CLI |

## 环境要求与安装

已实测：**macOS Apple Silicon、Python 3.12、FFmpeg 9.0.2、Final Cut Pro 10.6.10**。Final Cut 是最后导入与导出成片所需软件；CLI/MCP启动及核心测试不要求安装它，未找到Apple DTD时明确记录校验不可用。Windows支持未验收，文件锁采用Unix `fcntl`。

```sh
git clone https://github.com/WUHAO19831214/fcp-teaching-editor-mcp.git
cd fcp-teaching-editor-mcp
brew install python@3.12 ffmpeg
./scripts/setup.sh
.venv/bin/fcp-edu doctor
```

`setup.sh` 使用现有Python创建 `.venv`，安装 `requirements.lock` 与本项目。已有Python可用 `FCP_EDU_PYTHON` 指定可执行文件。首次ASR使用从模型仓库下载权重，后续缓存复用；这不是上传视频。默认 small，支持 tiny/base/small/medium/large-v2/large-v3；较大模型的CPU耗时可能明显增加。

不采用setup脚本时：

```sh
python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements.lock
.venv/bin/python -m pip install --no-deps -e .
```

PyAV锁定15.1.0（依赖范围 `<16`），避免已观察到的ASR调用兼容问题。`FFMPEG_PATH` / `FFPROBE_PATH` 可指定已安装程序。没有把FFmpeg二进制、模型权重或Apple DTD打包进仓库。

## 启动 MCP 与配置客户端

服务使用 **stdio**，由MCP客户端启动，没有HTTP地址。可直接运行：

```sh
.venv/bin/fcp-edu serve
# 等价入口：
.venv/bin/fcp-edu-mcp
```

终端中等待stdin是正常状态。验证真实初始化和工具发现：

```sh
.venv/bin/python scripts/mcp_smoke.py
```

生成本机配置（不改现有客户端配置）：

```sh
.venv/bin/python scripts/configure_clients.py
```

结果位于Git忽略的 `.local-config/`；合并对应客户端文件并刷新MCP。仓库中的 [Codex模板](examples/codex.mcp.toml) 和 [Antigravity模板](examples/antigravity.mcp.json) 使用 `<PROJECT_ROOT>` 占位符，须替换为自己的完整仓库路径。需要自动合并两种已安装客户端时才用 `--apply`，它会备份并在既有同名服务器不匹配时停止；没有Codex CLI则手工合并模板。

## 如何使用

推荐向Agent给出自己的视频绝对路径，并说明保留什么：

> 分析这段双缝干涉教学录屏，校正物理术语，先保留全部讲解、计数和公式。找出气口候选，给我具体源区间审核。

> 按紧凑气口预设做试剪。实验观察和参数输入需要保留；讲解保持1倍速。列出候选ID与源时间。

> 接受刚才列出的具体区间，生成新的Final Cut工程和SRT，保留上一版。

MCP顺序：`analyze_video` → `job_status` → `read_project` 全部分页 → `video_contact_sheet` → `correct_transcript` / `propose_edits` / `propose_rhythm_edits` → `read_edit_plan` → 适用授权后 `review_edits` / `set_speed` → `export_fcpxml`。

**所有工具时间都是被分析源媒体秒数**，不是剪后时间。每次修改先读当前revision；stale时重新核对，不能盲重试。批量threshold只处理孤立“嗯/呃”的删除提议，其他气口/等待/重复必须审核具体ID。接受 `keep` 保留内容，接受 `review` 建议代表明确执行该候选删除。

CLI可独立使用。以下 `PROJECT` 从分析结果取得，revision也须以inspect输出为准：

```sh
.venv/bin/fcp-edu analyze ./lesson.mp4 --model small
# 替换为返回的project_path；后续不假定固定项目ID：
PROJECT="projects/p-xxxxxxxxxxxx"
.venv/bin/fcp-edu inspect "$PROJECT"
.venv/bin/fcp-edu rhythm "$PROJECT" --revision 0
# 检查新revision、候选和原声后，按实际值审核：
.venv/bin/fcp-edu review "$PROJECT" --revision 1 --decision accept --ids rhythm-实际ID --authorization "接受所列具体源区间"
.venv/bin/fcp-edu export "$PROJECT" --revision 2
```

上述ID为占位符，不能照抄执行。更完整的术语校正、保护、变速和JSON参数见 [使用指南](docs/USAGE.md)。

### 安装紧凑气口 skill

仓库包含 [fcp-teaching-rhythm](skills/fcp-teaching-rhythm/SKILL.md)，复制到自己的Codex技能目录即可：

```sh
mkdir -p ~/.codex/skills
cp -R skills/fcp-teaching-rhythm ~/.codex/skills/
```

之后可调用 `$fcp-teaching-rhythm`。技能保存教学保护、证据来源、逐区间审核与成片比较经验；不是额外MCP服务器，也不授予未来视频的自动删除权限。

## 导入 Final Cut 与成片

1. 查看导出目录的 `editing_report.html`，核对字幕、已接受区间和授权。
2. Final Cut → 文件 → 导入 → XML，选择 `project.fcpxml`。导出指定独立新资源库，外部引用源媒体。
3. 查看媒体在线、字幕、原音轨、帧率、总时长和变速。原生Caption为 iTT / 简体中文 `cmn-Hans`。
4. 从Final Cut另存XML到另一个文件或 `.fcpxmld`，比较：

```sh
.venv/bin/fcp-edu verify-import ./export-folder ./fcp-returned.fcpxmld
```

每份导出初始 `fcp_import=not_verified`；结构/DTD合法不能证明导入成功。比较成功只说明独立回导的指定工程元数据一致，GUI观察和成片试听仍需单独完成。最后通过Final Cut共享导出MP4；通用MCP不提供这一GUI/渲染自动化。

本机默认 **FCPXML1.10**。1.14只有匹配本机DTD才可请求，未作为本机兼容功能验收。Basic Title已在独立案例完成静态与回导检查；白黄样式、额外分句和MP4制作仍是案例/Agent流程，不属于通用导出器的完整样式功能。

## 可复现公开演示

不使用私人素材也可实际跑一遍（macOS需Tingting语音）：

```sh
.venv/bin/python scripts/public_demo.py --apply-demo-cuts
```

它生成原创双缝示意图与中文合成语音，运行真实small ASR、按已知合成讲稿核对并校正术语/小数拼接、保护观察区、提出气口候选、在显式flag下仅接受合成静音示例切口，并生成工程与报告。默认输出 `test-artifacts/public-demo/`，目录已存在时停止，避免覆盖。换目录可用 `--output test-artifacts/another-demo`。演示语音不代表真实课堂识别准确率；输出FCP导入状态仍需独立验收。

## 目录结构

```text
src/fcp_edu_mcp/       # CLI、MCP、分析、审核、映射和导出
  data/               # 中文物理词汇
  vendor/             # 固定SHA的MIT模块与原许可证
scripts/              # 安装、配置、演示、MCP与来源验证
skills/               # 可安装的气口精剪skill
examples/             # 不含本机路径的MCP配置模板
tests/                # 审核、保护、修订、映射与回导测试
docs/                 # 使用、验证与真实截图
research/             # 来源元数据及vendor哈希清单
projects/             # 本地项目数据；Git忽略
test-artifacts/       # 媒体、演示和验收产物；Git忽略
```

## 验证、开发与已实现程度

```sh
.venv/bin/python -m pytest -q
.venv/bin/python scripts/check_vendor.py
.venv/bin/python -m pip wheel --no-deps . --wheel-dir dist
.venv/bin/python scripts/mcp_smoke.py
```

本机核心测试 **30项通过**；独立环境锁定依赖安装、wheel安装、`pip check`、doctor及真实MCP stdio初始化/工具调用已验证。来源校验确保5个MIT代码文件与3份许可证保持原字节。本版本以本地实际执行记录为依据，尚未配置GitHub Actions。

真实教学录屏试剪另完成本地ASR、审核、同步字幕、独立FCP导入/回导和成片核验：一个约550.4s案例删41处/55.7s，输出494.7s，用户反馈节奏有改善且不突兀。该单例不是识别准确率或通用最佳压缩比。完整证据范围、失败经历与公开演示验收见 [验证记录](docs/VALIDATION.md) 和 [发布检查](docs/RELEASE_VALIDATION.md)。私人媒体、日志、原始验收产物不公开。

## 已知限制与后续方向

- 单素材、单声道/立体声、正方形像素、Rec.709、无旋转、流起点接近零；支持常见CFR与1001分母帧率。VFR/HDR/非零起点需独立规范化副本；不覆盖原片。
- CFR检查为前60秒PTS与平均/标称帧率核对，不是全长逐帧认证。多机位、多素材和任意已有复杂FCP工程不在MVP范围。
- ASR可能漏语音、口癖或误认专业词；VAD不能判断教学意义；未做中文数据集CER、术语recall或呼吸精度评估。
- 本机FCP10.6.10案例曾发生持续播放无响应；静态画面、回导与MP4核验不能证明实时播放稳定。
- 通用ASR仍为faster-whisper CPU；MLX交叉识别是独立案例脚本，WhisperX/字级alignment尚未集成。
- CommandPost、实时GUI控制、通用MP4渲染、新版FCP兼容和更多字幕样式属于后续独立验收方向。

下一阶段优先完善规范化输入、公开语音评测样本和GUI导入/成片验收工具，再扩展MLX adapter与更多素材类型。架构与演进参见 [架构研究](ARCHITECTURE_RESEARCH.md)、[开发计划](DEVELOPMENT_PLAN.md)。

## 数据与许可

代码采用 [MIT](LICENSE)。MIT第三方文件保留完整原许可证及固定来源，见 [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES.md)。受限制的Final-Cut-Pro-AutoCaption源码未复用、未分发。Apple DTD、FFmpeg和模型权重均由用户环境提供，不重新分发。

原片、raw转写与私有课程输出不进入仓库；配置、密钥、日志和资源库由 `.gitignore` 排除。HTML报告、FCPXML和项目JSON会包含源路径、转写或授权记录，分享自己的导出前仍应检查这些数据。贡献时遵循 [CONTRIBUTING](CONTRIBUTING.md)，不要在Issue上传私人课程或账号信息。