mcncarl/jianying-headless

选用指南

AI 根据 README 整理 · 2026/10/11 11:59:23

适用场景

适用于 AI 视频工作流的工程交接、批量草稿生成和 Agent 辅助剪辑。

查看 README 依据

# Jianying Headless 面向剪映专业版 macOS 的本地自动化工具。通过结构化剪辑计划生成可编辑草稿， 在独立副本中修改多轨工程，并调用本机剪映引擎导出 MP4。 **主要适配版本：11.5.0 · 兼容版本：11.4.2** **首次使用请从 [从零生成第一个剪映草稿](docs/GETTING-STARTED.md) 开始。** 教程包含安装前提、环境检查、拖入自己的视频、首页登记、保存重开和常见报错处理。 11.5.0 仍需匹配具体安装身份与工具链，尚不保证任意电脑安装即用。 项目适用于 AI 视频工作流的工程交接、批量草稿生成和 Agent 辅助剪辑。 提供 Python 命令行入口及配套 Agent Skill。它不是剪映官方 SDK，运行时需要安装匹配版本的剪映。 ## 核心功能 | 功能 | 支持范围 | | --- | --- | | 生成可编辑草稿 | 视频分段、多轨组合、变速、音量、画中画、字幕和标题 | | 导入本地素材 | 视频、PNG、JPEG、GIF、配音、音乐和音效 | | 本地字体 | 新建文字或在副本中换字体，静态 OTF/TTF 随草稿保存；详见[字体说明](docs/LOCAL-FONTS.md) | | 基础动画 | 位置、缩放、旋转、透明度和音量的线性关键帧 |

使用方式

提供 Python 命令行入口，通过 headless_draft.py 执行 doctor、build、verify-build、publish、export 等命令。

查看 README 依据

cd jianying-headless python3 tools/build_native_codec.py python3 skills/yichen-jianying-edit/scripts/headless_draft.py doctor ``` `doctor` 是**环境检查命令**：检查剪映版本、组件身份和必要工具。 检查通过表示环境符合运行条件，不代表任意草稿都已通过画面、声音或导出验收。 桥接构建只编译项目源码并链接本机已安装程序库，不下载剪映、不修改官方库或账号权益。 编译结果必须匹配固定哈希，否则停止。 按 [计划格式](skills/yichen-jianying-edit/references/headless-macos.md) 准备 JSON， 或参考 [基础计划](examples/basic.plan.json) 和 [Hypit 交接格式示例](examples/hypit-handoff.plan.json)。 示例中的素材路径须替换为有权使用的本地文件。 ```bash python3 skills/yichen-jianying-edit/scripts/headless_draft.py build \

--plan /absolute/path/to/plan.json --out "$PWD/work/new-build" python3 skills/yichen-jianying-edit/scripts/headless_draft.py verify-build \ --build "$PWD/work/new-build" ``` 保存当前工作并完全退出剪映后，将新草稿登记到本机首页： ```bash python3 skills/yichen-jianying-edit/scripts/headless_draft.py publish \ --build "$PWD/work/new-build" --audit "$PWD/work/new-publish-audit" ``` `publish` 在此仅指本机首页登记，不是互联网发布。生成的草稿仍需实际打开、播放和保存检查。 需要成片时，可独立导出已验证快照： ```bash python3 skills/yichen-jianying-edit/scripts/headless_draft.py export \ --build "$PWD/work/new-build" --out "$PWD/work/new-export" ```

部署要求

需要 Apple Silicon Mac、macOS 26.0+、剪映专业版 11.5.0 或 11.4.2、Python 3.9+、FFmpeg/ffprobe、Xcode Command Line Tools。

查看 README 依据

详见 [Hypit 协作案例](docs/HYPIT-COLLABORATION.md) 和 [媒体说明](docs/media/README.md)。 当前转换是单向、按项目实现；不提供任意 Hypit 工程的一键无损转换或双向同步。 ## 运行环境 - Apple Silicon Mac，macOS 26.0+；已验证环境为 macOS 26.5.1。 - 剪映专业版 11.5.0，或兼容配置对应的 11.4.2。 - Python 3.9+、FFmpeg / ffprobe、Xcode Command Line Tools。 - 已验证桥接工具链：Apple clang 21.0.0 / macOS SDK 26.5。 应用版本、build、官方库哈希、签名与开发者身份均有检查。 未知版本或不匹配组件会被拒绝，不通过放宽校验强行运行。干净机器安装验收尚未完成。 官方引擎、账号数据、原始工程素材库和效果资源不随源码分发。 构建工具选择、安装诊断、登记恢复及字体支持的进展和待验限制见 [Issue 修复进展](docs/ISSUE-REMEDIATION.md)。环境检查通过不等于任意电脑兼容。 ## 快速开始 ```bash git clone https://github.com/mcncarl/jianying-headless.git

已知限制

不支持任意剪映版本、任意效果组合、在线模板、资源下载、云端工程或账号权益获取；复合片段仅支持实验性离线修改；图片/GIF 样本曾出现间歇少一帧；高清黑白滤镜与橙色描边花字已退出支持范围。

查看 README 依据

输出目录须不存在，成片为该目录下的 `render.mp4`。 导出在隔离进程中运行，默认不联网、不读取账号数据。 ## Agent Skill `skills/yichen-jianying-edit/` 提供 Agent 调用入口、口播计划辅助脚本与操作参考。 Skill 不包含剪映引擎；独立安装后仍需检出核心项目，并指定其路径： ```bash export JIANYING_HEADLESS_ROOT="/absolute/path/to/jianying-headless" ``` 安装说明见 [独立 Skill](skills/yichen-jianying-edit/README.md)。 Skill 另收录于 [yichen-skills](https://github.com/mcncarl/yichen-skills/tree/main/yichen-jianying-edit)。 ## 当前限制 - 复合片段仅支持实验性的离线修改与冻结快照导出，尚不能交付为保存可靠的可编辑嵌套草稿。 - 图片/GIF 样本曾出现间歇少一帧；严格帧数检查会拒绝缺帧输出，根因尚未解决。 - 不支持任意剪映版本、任意效果组合、在线模板、资源下载、云端工程或账号权益获取。 - 高清黑白滤镜与橙色描边花字已退出支持范围；含这些效果的计划或旧快照会明确报错。