Jianying Headless (Windows 兼容版)

剪映专业版 Windows 自动化草稿构建与多轨剪辑引擎
原生兼容剪映 5.x / 6.x / 9.x / 11.x，告别“草稿内容已损坏”，支持自定义存盘盘符与 AI Agent（Gemini / Claude Code / Cursor）一键直连。

---

🌟 项目简介

本项目针对剪映专业版（Jianying Pro Windows）开发，致力于解决将本地视频、音频、字幕自动化编译为剪映原生可编辑工程的完整生命周期管理。

与单纯合成 MP4 成片不同，本项目交付的是原生的剪映草稿工程：

• 完整保留视频多轨、音频多轨、画中画（PIP）、字幕文本与样式。
• 允许创作者在剪映客户端中二次精修、添加滤镜特效、微调关键帧或直接导出。

---

🛠️ Windows 核心适配与“草稿损坏”攻坚修复

原版项目多为 macOS 设计，在 Windows 环境下直接移植常出现**“无法打开草稿，草稿内容已损坏”**的报错。本项目完成了以下关键底层攻坚：

1. 速度材质伴生引用（speeds 绑定）：
   • 剪映 5.x 及以上版本对视频和音频片段引入了严格的材质链校验。每个视频/音频 segment 必须在 materials.speeds 材质池中注册伴生速度对象，并在分段的 extra_material_refs 中精确关联。
2. 多盘符元数据绝对路径校准：
   • Windows 下用户常将草稿存放在非系统盘（如 E:\剪映草稿位置\JianyingPro Drafts）。
   • 本项目在导出时自动将 draft_meta_info.json 中的 draft_root_path 与 draft_fold_path 修正为真实的物理盘符，避免跨盘符移动时路径校验失败。
3. 微秒级时间轴与全轨道元数据补全：
   • 时间戳统一采用整数微秒（1秒 = 1,000,000 us）。
   • 补齐画布配置（canvas_config）、轨道层级、渲染索引等 30+ 处缺失字段。

---

🚀 快速开始

1. 环境准备

• 操作系统：Windows 10 / 11
• Python：3.9+ (建议 3.10 / 3.11)
• 剪映专业版：已安装并能正常运行

# 克隆仓库
git clone https://github.com/your-username/jianying-headless-windows.git
cd jianying-headless-windows

# 安装依赖 (可选，主要用于进程与窗口自动化)
pip install -r requirements.txt

2. 双击一键启动（新手推荐）

进入项目文件夹，直接双击运行： 👉 快速启动.bat (或 run.bat)

按回车即可全自动完成：

1. 依赖与草稿存盘路径检测；
2. 自动生成标准测试草稿；
3. 直接发布至剪映存盘目录；
4. 自动唤起剪映专业版。

---

📖 CLI 命令行与高级用法

通过 headless_draft_win.py 调度器可以实现完整的脚本化控制：

1. 环境与路径体检 (doctor)

python headless_draft_win.py doctor

2. 配置自定义存盘路径 (config)

# 查看当前存盘路径
python headless_draft_win.py config

# 修改并锁定存盘路径 (如 E盘)
python headless_draft_win.py config --draft-dir "E:\剪映草稿位置\JianyingPro Drafts"

3. 根据计划编译草稿并直接拉起剪映 (build)

python headless_draft_win.py build --plan examples/sample_plan.json --publish --launch

---

📋 剪辑计划配置 (plan.json) 说明

编辑 examples/sample_plan.json 或传入自定义 JSON 即可实现批量自动化多轨合成：

{
  "project_name": "我的剪辑工程",
  "resolution": {
    "width": 1920,
    "height": 1080,
    "fps": 30
  },
  "segments": [
    {
      "path": "D:/素材/镜头A.mp4",
      "start_sec": 0,
      "duration_sec": 5.0,
      "is_main": true,
      "volume": 1.0
    },
    {
      "path": "D:/素材/画中画.mp4",
      "start_sec": 1.0,
      "duration_sec": 4.0,
      "is_main": false,
      "scale": 0.4,
      "pos_x": 0.5,
      "pos_y": 0.5,
      "volume": 0.3
    }
  ],
  "audios": [
    {
      "path": "D:/素材/BGM.mp3",
      "start_at_sec": 0,
      "volume": 0.5
    }
  ],
  "subtitles": [
    {
      "text": "欢迎观看自动化剪辑演示",
      "start_sec": 0.5,
      "duration_sec": 3.5
    }
  ]
}

---

🤖 AI Agent 接入支持 (Claude Code / Cursor / Gemini Spark)

本项目原生内置了面向 AI 智能体的上下文配置：

• SKILL.md：符合 Agent Skills 协议的标准 Skill 描述定义。
• CLAUDE.md：面向 Claude Code 等终端智能体的环境指令。

智能体可直接读取本规范，接收用户输入的自然语言剪辑指令，自动输出 plan.json 并调用 CLI 注入剪映。

---

📄 开源许可证

本项目基于 MIT License 开源。