{"id":"47337f2f-bc8a-40cc-a0ce-7fcec3e44da8","slug":"fcp-teaching-editor-mcp","kind":"mcp","name":"fcp-teaching-editor-mcp","summary":"Review-first Chinese teaching video editing for Final Cut Pro: local ASR, auditable cuts, synchronized captions, and FCPXML handoff.","owner":"WUHAO19831214","repoUrl":"https://github.com/WUHAO19831214/fcp-teaching-editor-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-10-04T12:17:30.000Z","addedAt":"2026-10-21T09:50:00.011Z","logoUrl":"https://avatars.githubusercontent.com/u/212445377?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["design-media"],"tags":["chinese-asr","education","fcpxml","final-cut-pro","python"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T20:34:15.968Z","sample":false,"url":"https://conduits.dev/tools/fcp-teaching-editor-mcp","language":"Python","transports":["stdio"],"install":{"pypi":"fcp-edu-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# FCP Teaching Editor MCP\n\n**面向中文教学视频的可审核剪辑工具：本地转写 → 术语校正 → 气口与停顿审核 → 同步字幕 → Final Cut Pro 工程。**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Python 3.12+](https://img.shields.io/badge/Python-3.12%2B-3776AB.svg)](pyproject.toml)\n\nFCP 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.\n\n当前版本 **0.1.0**。这是 Python CLI / MCP 服务与 HTML 审核报告，适合与 Codex、Antigravity 等支持 MCP 的 Agent 配合使用。**它没有独立桌面编辑器，也不自动控制 Final Cut 或直接渲染 MP4。**\n\n## 为什么开发\n\n教学录屏和实验讲解中，气口、口癖、试操作和等待会拖慢节奏，但静音也可能正在展示计数、板书、实验现象或推导步骤。普通“自动删静音”容易删掉教学信息；中文专业词汇识别错误，又会使字幕与公式失真。\n\n本项目把这些决策分开：工具提供原始转写、源时间、关键帧与剪辑候选；Agent结合物理语境校正和解释；用户授权具体修改；最后按同一帧映射生成素材片段和字幕，并到 Final Cut 验证真实导入效果。\n\n典型场景是高中物理实验教学、软件操作演示和单素材中文课程。双缝干涉案例中的条纹计数、双缝间距、屏距和波长公式属于应保护的讲解语境；本项目不采集传感器数据、不测量干涉条纹、不实现计算机视觉实验分析。\n\n## 实际运行截图\n\n以下截图来自公开演示脚本生成的原创示意图与 macOS 中文合成讲解，实际经过本项目的 ASR、审核和导出流程；示意图不是实验测量数据。截图隐藏了本机路径，没有使用私人课程录像。\n\n![实际生成的审核报告](docs/images/review-report.jpg)\n\n*HTML 审核报告显示源帧与最终帧、候选原因、审核状态和源区间。未批准的候选仍保留。*\n\n![实际字幕与时间映射报告](docs/images/subtitle-mapping.jpg)\n\n*源时间与最终时间共用整数帧映射，方便检查切口、字幕和授权。*\n\n![Final Cut Pro 导入演示工程](docs/images/final-cut-handoff.png)\n\n*独立测试资源库中的实际导入工程。Final Cut 的查看和回导是单独验收步骤，不属于 MCP 自动 GUI 控制。*\n\n## 核心功能与特色\n\n| 功能 | 当前实现 |\n|---|---|\n| 素材检查 | ffprobe 检查流、时长、帧率、音轨、颜色/旋转约束与 SHA256；独立派生音频、六帧联系表 |\n| 中文转写 | faster-whisper，CPU int8，实际 word/token spans、segments、识别概率与术语提示 |\n| 专业术语校正 | 内置物理词汇与自定义 aliases；连续原始 word IDs、精确 before、after/reason 绑定，保留原时段 |\n| 审核候选 | 中文口癖、相邻重复、自我纠正提示、长停顿、语音间隙与声学疑似呼吸，全部默认 pending |\n| 紧凑气口 | `compact-teaching-v1`：ASR、校正短句、Silero VAD及可选独立语音跨度并集，向内取整到帧 |\n| 教学保护 | 指定源区间保护；讲解默认 1×；气口、实验等待和重复解释须按具体区间审核 |\n| 变速 | 指定不重叠源区间 0.25–4×；默认拒绝已识别语音上的非1×变速；记录请求/实际量化速度 |\n| 可撤销与审计 | 原片/raw只读；追加修订、journal、checksum、expected revision、undo 创建新修订 |\n| 同步导出 | 新目录中的 FCPXML、简体中文原生 iTT Caption 或 Basic Title、SRT、HTML、timeline/manifest |\n| 导入比较 | 本机 Apple DTD/结构校验；另存 Final Cut XML后比较时长、片段、速度、字幕与音轨元数据 |\n\n特色是**可复核、保留教学意义、字幕与素材共用映射**，不是识别模型自身能理解全部教学内容。候选 confidence 是未校准启发式评分；ASR token spans不是逐汉字强制对齐。\n\n## 工作原理与技术架构\n\n```mermaid\nflowchart LR\n    A[本地源视频] --> B[ffprobe 与派生音频和关键帧]\n    B --> C[本地中文 ASR]\n    C --> D[不可变原始转写]\n    D --> E[Agent 术语校正与语境审核]\n    B --> F[声学与 VAD 候选]\n    E --> G[待审核剪辑计划]\n    F --> G\n    G --> H[用户授权与保护区]\n    H --> I[整数帧时间映射]\n    I --> J[FCPXML 与 SRT 与 HTML]\n    J --> K[Final Cut 实际导入与独立回导]\n```\n\n工具不需要另配付费 LLM API Key。专业语义判断由使用 MCP 的 AI host 完成；本地识别和音视频处理留在本机，但发送给 host 的转写/图像受该 host 的数据政策影响，因此不能把整个工作流称为完全离线。\n\n主要技术：Python 3.12、官方 MCP SDK FastMCP stdio、FFmpeg/ffprobe、faster-whisper/CTranslate2、Silero VAD、NumPy、Pillow、Fraction/整数帧、defusedxml、Apple FCPXML DTD、pytest。\n\n| 模块 | 职责 |\n|---|---|\n| `media.py` | 媒体真值、格式约束、派生音频/帧、环境诊断 |\n| `analysis.py` | 中文 ASR、术语表、初始启发式建议 |\n| `rhythm.py` | 语音范围并集、气口缓冲、保护及重复候选过滤 |\n| `editing.py` | 校正、提议、审核、变速、保护、撤销 |\n| `storage.py` | 文件锁、源完整性、原子指针、不可变修订 |\n| `timeline.py` | 源帧到输出帧映射、字幕分句与SRT |\n| `export.py` / `verification.py` | FCPXML适配、HTML报告、结构/DTD检查与独立回导比较 |\n| `server.py` / `cli.py` | MCP工具、后台分析任务与同一core的CLI |\n\n## 环境要求与安装\n\n已实测：**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`。\n\n```sh\ngit clone https://github.com/WUHAO19831214/fcp-teaching-editor-mcp.git\ncd fcp-teaching-editor-mcp\nbrew install python@3.12 ffmpeg\n./scripts/setup.sh\n.venv/bin/fcp-edu doctor\n```\n\n`setup.sh` 使用现有Python创建 `.venv`，安装 `requirements.lock` 与本项目。已有Python可用 `FCP_EDU_PYTHON` 指定可执行文件。首次ASR使用从模型仓库下载权重，后续缓存复用；这不是上传视频。默认 small，支持 tiny/base/small/medium/large-v2/large-v3；较大模型的CPU耗时可能明显增加。\n\n不采用setup脚本时：\n\n```sh\npython3.12 -m venv .venv\n.venv/bin/python -m pip install -r requirements.lock\n.venv/bin/python -m pip install --no-deps -e .\n```\n\nPyAV锁定15.1.0（依赖范围 `<16`），避免已观察到的ASR调用兼容问题。`FFMPEG_PATH` / `FFPROBE_PATH` 可指定已安装程序。没有把FFmpeg二进制、模型权重或Apple DTD打包进仓库。\n\n## 启动 MCP 与配置客户端\n\n服务使用 **stdio**，由MCP客户端启动，没有HTTP地址。可直接运行：\n\n```sh\n.venv/bin/fcp-edu serve\n# 等价入口：\n.venv/bin/fcp-edu-mcp\n```\n\n终端中等待stdin是正常状态。验证真实初始化和工具发现：\n\n```sh\n.venv/bin/python scripts/mcp_smoke.py\n```\n\n生成本机配置（不改现有客户端配置）：\n\n```sh\n.venv/bin/python scripts/configure_clients.py\n```\n\n结果位于Git忽略的 `.local-config/`；合并对应客户端文件并刷新MCP。仓库中的 [Codex模板](examples/codex.mcp.toml) 和 [Antigravity模板](examples/antigravity.mcp.json) 使用 `<PROJECT_ROOT>` 占位符，须替换为自己的完整仓库路径。需要自动合并两种已安装客户端时才用 `--apply`，它会备份并在既有同名服务器不匹配时停止；没有Codex CLI则手工合并模板。\n\n## 如何使用\n\n推荐向Agent给出自己的视频绝对路径，并说明保留什么：\n\n> 分析这段双缝干涉教学录屏，校正物理术语，先保留全部讲解、计数和公式。找出气口候选，给我具体源区间审核。\n\n> 按紧凑气口预设做试剪。实验观察和参数输入需要保留；讲解保持1倍速。列出候选ID与源时间。\n\n> 接受刚才列出的具体区间，生成新的Final Cut工程和SRT，保留上一版。\n\nMCP顺序：`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`。\n\n**所有工具时间都是被分析源媒体秒数**，不是剪后时间。每次修改先读当前revision；stale时重新核对，不能盲重试。批量threshold只处理孤立“嗯/呃”的删除提议，其他气口/等待/重复必须审核具体ID。接受 `keep` 保留内容，接受 `review` 建议代表明确执行该候选删除。\n\nCLI可独立使用。以下 `PROJECT` 从分析结果取得，revision也须以inspect输出为准：\n\n```sh\n.venv/bin/fcp-edu analyze ./lesson.mp4 --model small\n# 替换为返回的project_path；后续不假定固定项目ID：\nPROJECT=\"projects/p-xxxxxxxxxxxx\"\n.venv/bin/fcp-edu inspect \"$PROJECT\"\n.venv/bin/fcp-edu rhythm \"$PROJECT\" --revision 0\n# 检查新revision、候选和原声后，按实际值审核：\n.venv/bin/fcp-edu review \"$PROJECT\" --revision 1 --decision accept --ids rhythm-实际ID --authorization \"接受所列具体源区间\"\n.venv/bin/fcp-edu export \"$PROJECT\" --revision 2\n```\n\n上述ID为占位符，不能照抄执行。更完整的术语校正、保护、变速和JSON参数见 [使用指南](docs/USAGE.md)。\n\n### 安装紧凑气口 skill\n\n仓库包含 [fcp-teaching-rhythm](skills/fcp-teaching-rhythm/SKILL.md)，复制到自己的Codex技能目录即可：\n\n```sh\nmkdir -p ~/.codex/skills\ncp -R skills/fcp-teaching-rhythm ~/.codex/skills/\n```\n\n之后可调用 `$fcp-teaching-rhythm`。技能保存教学保护、证据来源、逐区间审核与成片比较经验；不是额外MCP服务器，也不授予未来视频的自动删除权限。\n\n## 导入 Final Cut 与成片\n\n1. 查看导出目录的 `editing_report.html`，核对字幕、已接受区间和授权。\n2. Final Cut → 文件 → 导入 → XML，选择 `project.fcpxml`。导出指定独立新资源库，外部引用源媒体。\n3. 查看媒体在线、字幕、原音轨、帧率、总时长和变速。原生Caption为 iTT / 简体中文 `cmn-Hans`。\n4. 从Final Cut另存XML到另一个文件或 `.fcpxmld`，比较：\n\n```sh\n.venv/bin/fcp-edu verify-import ./export-folder ./fcp-returned.fcpxmld\n```\n\n每份导出初始 `fcp_import=not_verified`；结构/DTD合法不能证明导入成功。比较成功只说明独立回导的指定工程元数据一致，GUI观察和成片试听仍需单独完成。最后通过Final Cut共享导出MP4；通用MCP不提供这一GUI/渲染自动化。\n\n本机默认 **FCPXML1.10**。1.14只有匹配本机DTD才可请求，未作为本机兼容功能验收。Basic Title已在独立案例完成静态与回导检查；白黄样式、额外分句和MP4制作仍是案例/Agent流程，不属于通用导出器的完整样式功能。\n\n## 可复现公开演示\n\n不使用私人素材也可实际跑一遍（macOS需Tingting语音）：\n\n```sh\n.venv/bin/python scripts/public_demo.py --apply-demo-cuts\n```\n\n它生成原创双缝示意图与中文合成语音，运行真实small ASR、按已知合成讲稿核对并校正术语/小数拼接、保护观察区、提出气口候选、在显式flag下仅接受合成静音示例切口，并生成工程与报告。默认输出 `test-artifacts/public-demo/`，目录已存在时停止，避免覆盖。换目录可用 `--output test-artifacts/another-demo`。演示语音不代表真实课堂识别准确率；输出FCP导入状态仍需独立验收。\n\n## 目录结构\n\n```text\nsrc/fcp_edu_mcp/       # CLI、MCP、分析、审核、映射和导出\n  data/               # 中文物理词汇\n  vendor/             # 固定SHA的MIT模块与原许可证\nscripts/              # 安装、配置、演示、MCP与来源验证\nskills/               # 可安装的气口精剪skill\nexamples/             # 不含本机路径的MCP配置模板\ntests/                # 审核、保护、修订、映射与回导测试\ndocs/                 # 使用、验证与真实截图\nresearch/             # 来源元数据及vendor哈希清单\nprojects/             # 本地项目数据；Git忽略\ntest-artifacts/       # 媒体、演示和验收产物；Git忽略\n```\n\n## 验证、开发与已实现程度\n\n```sh\n.venv/bin/python -m pytest -q\n.venv/bin/python scripts/check_vendor.py\n.venv/bin/python -m pip wheel --no-deps . --wheel-dir dist\n.venv/bin/python scripts/mcp_smoke.py\n```\n\n本机核心测试 **30项通过**；独立环境锁定依赖安装、wheel安装、`pip check`、doctor及真实MCP stdio初始化/工具调用已验证。来源校验确保5个MIT代码文件与3份许可证保持原字节。本版本以本地实际执行记录为依据，尚未配置GitHub Actions。\n\n真实教学录屏试剪另完成本地ASR、审核、同步字幕、独立FCP导入/回导和成片核验：一个约550.4s案例删41处/55.7s，输出494.7s，用户反馈节奏有改善且不突兀。该单例不是识别准确率或通用最佳压缩比。完整证据范围、失败经历与公开演示验收见 [验证记录](docs/VALIDATION.md) 和 [发布检查](docs/RELEASE_VALIDATION.md)。私人媒体、日志、原始验收产物不公开。\n\n## 已知限制与后续方向\n\n- 单素材、单声道/立体声、正方形像素、Rec.709、无旋转、流起点接近零；支持常见CFR与1001分母帧率。VFR/HDR/非零起点需独立规范化副本；不覆盖原片。\n- CFR检查为前60秒PTS与平均/标称帧率核对，不是全长逐帧认证。多机位、多素材和任意已有复杂FCP工程不在MVP范围。\n- ASR可能漏语音、口癖或误认专业词；VAD不能判断教学意义；未做中文数据集CER、术语recall或呼吸精度评估。\n- 本机FCP10.6.10案例曾发生持续播放无响应；静态画面、回导与MP4核验不能证明实时播放稳定。\n- 通用ASR仍为faster-whisper CPU；MLX交叉识别是独立案例脚本，WhisperX/字级alignment尚未集成。\n- CommandPost、实时GUI控制、通用MP4渲染、新版FCP兼容和更多字幕样式属于后续独立验收方向。\n\n下一阶段优先完善规范化输入、公开语音评测样本和GUI导入/成片验收工具，再扩展MLX adapter与更多素材类型。架构与演进参见 [架构研究](ARCHITECTURE_RESEARCH.md)、[开发计划](DEVELOPMENT_PLAN.md)。\n\n## 数据与许可\n\n代码采用 [MIT](LICENSE)。MIT第三方文件保留完整原许可证及固定来源，见 [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES.md)。受限制的Final-Cut-Pro-AutoCaption源码未复用、未分发。Apple DTD、FFmpeg和模型权重均由用户环境提供，不重新分发。\n\n原片、raw转写与私有课程输出不进入仓库；配置、密钥、日志和资源库由 `.gitignore` 排除。HTML报告、FCPXML和项目JSON会包含源路径、转写或授权记录，分享自己的导出前仍应检查这些数据。贡献时遵循 [CONTRIBUTING](CONTRIBUTING.md)，不要在Issue上传私人课程或账号信息。\n"}