JianYing Bridge

安全地把一个紧凑的 JSON 剪辑计划编译成可继续编辑的剪映专业版草稿。

A local Codex plugin and MCP server that compiles one compact JSON edit plan into a new, editable JianYing Pro draft.

非剪映官方项目。当前实机验证环境：macOS + 剪映专业版 11.4.2。

为什么做它

很多剪映自动化项目仍输出旧版 draft_content.json，或直接修改用户已有工程。JianYing Bridge 选择了更保守的边界：

• 只创建新草稿，不覆盖、删除或修补现有草稿；

• 先在沙盒生成并校验，再显式发布到剪映草稿库；

• 视频、音频会复制进草稿自身，降低 macOS 权限和源文件移动导致的丢失风险；

• 一次提交完整 manifest，避免“一个片段一次工具调用”的高频往返；

• 全程使用本地素材和本机工具，本身不消耗图片/视频生成额度。

Related MCP server: jianying-local-mcp

已验证能力

• 剪映专业版 11.4.2（macOS）可发现并打开生成的草稿；

• 视频、BGM、中文字幕可正常进入时间线并播放；

• 剪映打开后会将草稿迁移为原生 Timelines/project.json 布局；

• 同名工程会被拒绝，绝不静默覆盖；

• MCP stdio 初始化、工具发现和调用通过；

• 5 项本地回归测试通过。

MCP 工具

快速开始

依赖：macOS、剪映专业版 11.4.x、Python 3.11+、uv、FFmpeg/FFprobe。

git clone https://github.com/DeathKnight88/jianying-bridge.git
cd jianying-bridge
./scripts/launch_jianying_bridge

若作为 Codex 插件使用，可把仓库目录注册为本地插件源；.mcp.json 已配置好 stdio 服务入口。新安装的插件需要在新的 Codex 任务中加载。

Manifest 示例

{
  "version": 1,
  "project": {
    "name": "My_New_Project",
    "width": 1920,
    "height": 1080,
    "fps": 30
  },
  "video": [
    {
      "path": "/absolute/path/clip.mp4",
      "start": 0,
      "source_start": 0,
      "duration": 3,
      "track": "VideoTrack",
      "transition": {"name": "叠化", "duration": 0.3}
    }
  ],
  "audio": [
    {
      "path": "/absolute/path/music.mp3",
      "start": 0,
      "duration": 3,
      "track": "BGM",
      "volume": 0.2
    }
  ],
  "text": [
    {
      "content": "字幕",
      "start": 0,
      "duration": 3,
      "track": "Subtitles"
    }
  ]
}

时间单位统一为秒。相对素材路径以 manifest 所在目录为基准。完整模板见 assets/example-manifest.json。

推荐工作流

本地素材
  → FFprobe / Whisper / BaoCut / auto-editor（可选）
  → 一份 edit manifest
  → JianYing Bridge 沙盒生成 + 校验
  → 发布到剪映
  → 人工预览与导出

桥接器只负责执行已经确定的剪辑计划。转写、脚本判断、镜头选择等工作建议在生成 manifest 前一次性完成。

当前限制

• v0.1 仅支持新建草稿，不编辑剪映 11.x 已有加密工程；

• 发布时要求剪映主进程关闭，避免项目索引并发写入；

• 最终预览和导出仍需在剪映中完成；

• 当前只在 macOS 剪映专业版 11.4.2 做过端到端验证；Windows 和其他版本欢迎测试反馈；

• 剪映内部格式属于非公开实现，版本升级可能导致兼容性变化。

开发与验证

uv run --with pytest pytest -q tests
uv run --with pyyaml python /path/to/plugin-creator/scripts/validate_plugin.py .

第三方代码

运行时包含经过固定版本的 luoluoluo22/jianying-editor-skill 与其内嵌的 pyJianYingDraft。许可证和修改说明见 THIRD_PARTY_NOTICES.md。

License

项目自身代码使用 MIT License。第三方代码继续遵循各自的 MIT 或 Apache-2.0 许可证。

“剪映”及相关商标归其权利人所有。本项目与字节跳动或剪映官方无隶属、授权或背书关系。