mcncarl/jianying-headless

Jianying Headless

面向剪映专业版 macOS 的本地自动化工具。通过结构化剪辑计划生成可编辑草稿， 在独立副本中修改多轨工程，并调用本机剪映引擎导出 MP4。

主要适配版本：11.5.0 · 兼容版本：11.4.2

首次使用请从 从零生成第一个剪映草稿 开始。 教程包含安装前提、环境检查、拖入自己的视频、首页登记、保存重开和常见报错处理。 11.5.0 仍需匹配具体安装身份与工具链，尚不保证任意电脑安装即用。

项目适用于 AI 视频工作流的工程交接、批量草稿生成和 Agent 辅助剪辑。 提供 Python 命令行入口及配套 Agent Skill。它不是剪映官方 SDK，运行时需要安装匹配版本的剪映。

核心功能

| 功能 | 支持范围 | | --- | --- | | 生成可编辑草稿 | 视频分段、多轨组合、变速、音量、画中画、字幕和标题 | | 导入本地素材 | 视频、PNG、JPEG、GIF、配音、音乐和音效 | | 本地字体 | 新建文字或在副本中换字体，静态 OTF/TTF 随草稿保存；详见字体说明 | | 基础动画 | 位置、缩放、旋转、透明度和音量的线性关键帧 | | 原生效果 | 六类静态几何蒙版、叠化转场、轻微抖动；需要匹配的本机资源与使用权限 | | 编辑已有工程 | 检查源草稿，在独立副本中修改，不覆盖原项目 | | 原生视频导出 | 通过本机剪映引擎将已验证快照导出为 H.264/AAC MP4 | | 环境与工程检查 | 核对运行版本、组件身份、素材完整性和草稿保存结果 |

核心流程为：素材与剪辑计划 → 可编辑剪映草稿 → 原生引擎导出。 剪映中后续手工修改的内容不会自动同步回原计划或旧导出快照。

Hypit 协作案例

一个约 50.23 秒的 IG 滚动动画教程展示了从 Hypit 到剪映的工程交接。 转换使用原工程的独立画面、配音、图片和文字时间安排，而不是仅导入一条最终成片。

| 工程内容 | 数量 | | --- | --- | | 原始素材 | 39 份 | | 视频与图片 | 8 条轨道、38 个片段 | | 独立配音 | 1 条轨道、7 个片段 | | 可编辑文字 | 14 条轨道、109 个片段 | | 合计 | 23 条轨道、154 个片段 |

该案例已在剪映 11.5.0 完成构建、打开播放、保存、完全退出、冷重开和结构回读， 并通过原生导出的 1507 / 1507 帧检查与完整解码检查。

画面对照

| Hypit 原成片 | 剪映工程原生导出 | | --- | --- | | | |

两组图片均取自真实案例的 1、8、17、28、37、48 秒。展示的是可编辑工程交接， 不是视觉无损转换：特殊字体、逐词颜色动画、部分裁切与阴影未原样保留， 第 37 秒的补充画面也存在差异。完整主观视听验收尚未完成。

详见 Hypit 协作案例 和 媒体说明。 当前转换是单向、按项目实现；不提供任意 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 修复进展。环境检查通过不等于任意电脑兼容。

快速开始

git clone https://github.com/mcncarl/jianying-headless.git
cd jianying-headless
python3 tools/build_native_codec.py
python3 skills/yichen-jianying-edit/scripts/headless_draft.py doctor

doctor 是环境检查命令：检查剪映版本、组件身份和必要工具。 检查通过表示环境符合运行条件，不代表任意草稿都已通过画面、声音或导出验收。

桥接构建只编译项目源码并链接本机已安装程序库，不下载剪映、不修改官方库或账号权益。 编译结果必须匹配固定哈希，否则停止。

按 计划格式 准备 JSON， 或参考 基础计划 和 Hypit 交接格式示例。 示例中的素材路径须替换为有权使用的本地文件。

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"

保存当前工作并完全退出剪映后，将新草稿登记到本机首页：

python3 skills/yichen-jianying-edit/scripts/headless_draft.py publish \
  --build "$PWD/work/new-build" --audit "$PWD/work/new-publish-audit"

publish 在此仅指本机首页登记，不是互联网发布。生成的草稿仍需实际打开、播放和保存检查。 需要成片时，可独立导出已验证快照：

python3 skills/yichen-jianying-edit/scripts/headless_draft.py export \
  --build "$PWD/work/new-build" --out "$PWD/work/new-export"

输出目录须不存在，成片为该目录下的 render.mp4。 导出在隔离进程中运行，默认不联网、不读取账号数据。

Agent Skill

skills/yichen-jianying-edit/ 提供 Agent 调用入口、口播计划辅助脚本与操作参考。 Skill 不包含剪映引擎；独立安装后仍需检出核心项目，并指定其路径：

export JIANYING_HEADLESS_ROOT="/absolute/path/to/jianying-headless"

安装说明见 独立 Skill。 Skill 另收录于 yichen-skills。

当前限制

• 复合片段仅支持实验性的离线修改与冻结快照导出，尚不能交付为保存可靠的可编辑嵌套草稿。
• 图片/GIF 样本曾出现间歇少一帧；严格帧数检查会拒绝缺帧输出，根因尚未解决。
• 不支持任意剪映版本、任意效果组合、在线模板、资源下载、云端工程或账号权益获取。
• 高清黑白滤镜与橙色描边花字已退出支持范围；含这些效果的计划或旧快照会明确报错。
• 工程结构检查、原生播放、视觉一致性、主观听感与素材许可是不同的验收项目。

详细结果及已知问题见 验证状态。

项目结构与验证

| 目录 | 内容 | | --- | --- | | engine/ | 草稿构建、独立副本编辑、资源校验与原生导出 | | bridge/ | 文件与管道桥接源码、保留来源声明的接口头文件 | | skills/ | Agent Skill 及配套参考 | | tools/、tests/ | 构建、源码包装检查与可移植测试 | | licenses/ | 第三方许可证 |

python3 tools/check_package.py
python3 -m unittest discover -s tests -v

专项原生测试的本机素材与证据不随仓库分发；源码检查不能替代实际工程验收。

许可与来源

原创部分采用 个人学习和非商业使用许可；商业使用需取得作者书面授权。 第三方内容继续适用原许可证，详见 第三方声明。 本项目不是 MIT / Apache-2.0 整包授权，代码许可也不包含剪映集成授权、账号权益或素材许可。 分发边界见 分发范围。