FCP Teaching Editor MCP

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

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 验证真实导入效果。

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

Related MCP server: YoloCut

实际运行截图

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

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

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

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

核心功能与特色

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

工作原理与技术架构

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。

环境要求与安装

已实测：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。

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脚本时：

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地址。可直接运行：

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

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

.venv/bin/python scripts/mcp_smoke.py

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

.venv/bin/python scripts/configure_clients.py

结果位于Git忽略的 .local-config/；合并对应客户端文件并刷新MCP。仓库中的 Codex模板 和 Antigravity模板 使用 <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输出为准：

.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参数见 使用指南。

安装紧凑气口 skill

仓库包含 fcp-teaching-rhythm，复制到自己的Codex技能目录即可：

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，比较：

.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语音）：

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

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

目录结构

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忽略

验证、开发与已实现程度

.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，用户反馈节奏有改善且不突兀。该单例不是识别准确率或通用最佳压缩比。完整证据范围、失败经历与公开演示验收见 验证记录 和 发布检查。私人媒体、日志、原始验收产物不公开。

已知限制与后续方向

• 单素材、单声道/立体声、正方形像素、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与更多素材类型。架构与演进参见 架构研究、开发计划。

数据与许可

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

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