KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

com.linker.jianying.sdk

★ 1 Open GitHub ↗

go剪影导出草稿

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# JianYing Draft SDK for Go

轻量、灵活的 Golang 剪映草稿生成工具。在 [pyJianYingDraft](https://github.com/GuanYixuan/pyJianYingDraft) 能力基础上，**额外支持剪映 5.9 左侧「导入/素材」面板与轨道静音**。

## 功能特性

- **草稿管理**: 创建、列出、删除剪映草稿
- **素材面板（剪映 5.9）**: `Save()` 时复制素材到素材库，并写入 `draft_meta_info.json` → `draft_materials`
- **轨道静音**: `WithMute(true)` → `tracks[].attribute=1` 且片段 `volume=0`
- **多轨道支持**: 视频、音频、文本、特效、滤镜、贴纸轨道
- **素材处理**: 视频/图片/音频素材导入（ffprobe 探测时长与分辨率）
- **视频编辑**: 时间截取、变速播放、图像调节
- **音频处理**: 淡入淡出、音量调节
- **特效系统**: 滤镜(106+)、转场(13)、蒙版(6)、混合模式(13)
- **动画效果**: 入场/出场动画、关键帧
- **文本功能**: 样式、描边、背景、阴影、气泡、花字、自动换行
- **字幕导入**: SRT 字幕文件导入
- **跨平台**: Windows / macOS / Linux（macOS 额外写入 `draft_info.json`）

## 与 pyJianYingDraft 的主要差异

| 项目 | pyJianYingDraft | 本 SDK（当前可用版本） |
|------|-----------------|------------------------|
| `Save()` 行为 | 仅写 `draft_content.json` | 写 content + 同步 meta + 复制素材库 |
| 左侧「导入/素材」 | 依赖剪映打开时自行索引 | **显式写入** `draft_materials[type=0].value` |
| 素材路径 | 保留原始绝对路径 | 复制到 `{素材库}/imported_时间戳/`，ASCII 哈希文件名 |
| 素材 ID | `uuid4().hex`（小写无连字符） | **大写 UUID**（如 `D9FCE516-...`） |
| 视频 `local_material_id` | 空字符串 `""` | 与 `id` 相同 |
| `draft_meta_info` | 创建时复制空模板，save 不更新 | save 时更新时长、路径、`draft_materials`、封面 |
| 轨道静音 | `attribute=int(mute)` | 同 py，且静音时片段 `volume=0` |
| 模板模式 / 自动导出 | 支持 | 暂未实现 |

> **说明**：时间轴播放仍由 `draft_content.json` 的 `materials` + `tracks` 驱动；素材面板额外依赖 `draft_meta_info.json` 与素材库路径一致。两者 `path` / `file_Path` 必须在 `Save()` 后指向同一文件。

## 安装

```bash
go get github.com/mackjosn/com.linker.jianying.sdk
```

## 依赖

- Go 1.22+
- FFmpeg（需要 `ffprobe`；生成封面时需要 `ffmpeg`）
- 剪映专业版 5.9+（已在 5.9.0 验证）

## 快速开始

### 基础示例（素材面板 + 静音）

```go
package main

import (
    "log"

jianying "github.com/mackjosn/com.linker.jianying.sdk"
)

func main() {
    folder, err := jianying.NewDraftFolder(
        `D:\JianyingPro Drafts`,
        jianying.WithFFprobePath(`ffprobe`),
    )
    if err != nil {
        log.Fatal(err)
    }

script, err := folder.CreateDraftSimple("my_draft", 1920, 1080, true)
    if err != nil {
        log.Fatal(err)
    }

// 静音视频轨道
    script.AddTrack(jianying.TrackTypeVideo, "", jianying.WithMute(true))

material, err := jianying.NewVideoMaterial("ffprobe", `E:\demo\video.mp4`, "")
    if err != nil {
        log.Fatal(err)
    }
    seg, err := jianying.NewVideoSegment(material, jianying.NewTimerange(0, material.Duration), nil)
    if err != nil {
        log.Fatal(err)
    }
    script.AddVideoSegment(seg, "")

// Save 会自动：复制素材库 → 写 draft_content → 写 draft_meta_info
    if err := script.Save(); err != nil {
        log.Fatal(err)
    }
}
```

运行示例（**先完全退出剪映**）：

```bash
cd com.linker.jianying.sdk
go run ./example/01_basic/
```

### 素材导入方式

SDK 提供了两种素材导入方式：

#### 方式1：自动探测（推荐）

```go
material, err := jianying.NewVideoMaterial(ffprobePath, videoPath, "")
```

- 自动使用 ffprobe 探测素材的时长、分辨率、类型等信息
- 适用于本地文件路径

#### 方式2：手动指定参数

```go
material, err := jianying.NewVideoMaterialWithOptions(
    videoPath,
    "素材名称",
    jianying.VideoMaterialFFprobePath(""),        // 空字符串表示跳过探测
    jianying.VideoMaterialID("CUSTOM_ID_001"),   // 自定义ID
    jianying.VideoMaterialDuration(15000000),     // 15秒
    jianying.VideoMaterialDimensions(1920, 1080), // 1080P
    jianying.VideoMaterialType(jianying.MaterialTypeVideo),
    jianying.VideoMaterialHasAudio(true),
)
```

- 适用于 URL 下载的素材、网络流媒体、无法通过 ffprobe 探测的素材等场景
- 支持混合使用：部分参数手动指定，未指定的参数自动探测

#### 轨道创建与素材导入的分离

SDK 的设计理念是将轨道创建与素材导入完全分离：

```go
// 1. 创建轨道（不涉及素材）
script.AddTrack(jianying.TrackTypeVideo, "main", jianying.WithMute(false), jianying.WithVisible(true))

// 2. 导入素材（不涉及轨道）
material := jianying.NewVideoMaterial(ffprobePath, videoPath, "")

// 3. 创建片段（连接素材与轨道）
seg := jianying.NewVideoSegment(material, jianying.NewTimerange(0, material.Duration), nil)

// 4. 添加片段到轨道
script.AddVideoSegment(seg, "main")

// 5. 保存草稿（同步素材库）
script.Save()
```

这种设计使得：
- 可以只创建轨道而不导入素材
- 可以只导入素材而不添加到轨道
- 素材导入与轨道创建完全解耦

### 三种场景对比验证

**01_basic** 示例演示了三种场景：

| 场景 | 草稿名称 | 操作 | 预期效果 |
|------|----------|------|----------|
| **场景1** | `only_material_demo` | 只导入素材，不创建轨道 | 剪映中素材库有素材，时间线为空 |
| **场景2** | `only_track_demo` | 只创建轨道，不导入素材 | 剪映中显示空轨道，素材库为空 |
| **场景3** | `material_plus_track_demo` | 导入素材 + 创建轨道 + 添加片段 | 完整的时间线 |

运行示例后会在剪映草稿目录下创建三个草稿文件夹，您可以在剪映中打开它们来验证不同的效果。

### Save() 内部流程

```
Save()
  ├─ syncMaterialsToLibrary()   # 复制到素材库，更新 materials.path / material_name
  ├─ Dump(draft_content.json)   # 写入时间轴与 materials
  ├─ Dump(draft_info.json)      # 仅 macOS
  └─ updateDraftMetaInfo()      # draft_materials、tm_duration、draft_cover 等
```

`Dump()`  alone **不会**同步素材库或 meta，不能替代 `Save()`。

## 路径配置

SDK 从剪映 `globalSetting` 读取目录（`%LOCALAPPDATA%\JianyingPro\User Data\Config\globalSetting`）：

| 配置项 | 用途 |
|--------|------|
| `currentCustomDraftPath` | 草稿目录（默认 `%LOCALAPPDATA%\...\com.lveditor.draft`） |
| `customMaterialPath` | 素材库目录（默认 `%LOCALAPPDATA%\...\Download`） |

也可在代码中直接指定草稿目录：`NewDraftFolder("D:\\JianyingPro Drafts")`。

## 使用注意

1. **保存前退出剪映**，否则 `.locked` 可能导致覆盖失败，或剪映改写 meta。
2. 素材文件名含中文时，SDK 会复制为 **ASCII 哈希名**（如 `0d8db8b3.mp4`），避免素材库索引失败。
3. `draft_materials` 使用剪映 5.9 **分类格式**：视频在 `type:0` 的 `value` 数组中。
4. 重新打开草稿后若素材消失，检查 `draft_meta_info.json` 中 `draft_materials[0].value` 是否被剪映清空。

## 验证记录（2026-06-04）

在 Windows + 剪映 5.9.0 环境验证通过：

- `go test ./...` 全部通过
- `example/01_basic` 生成草稿可正常打开
- `draft_materials[0].value` 含视频条目，`file_Path` 指向 `imported_*/哈希名.mp4`
- 素材文件已复制到素材库，并生成 `draft_cover.jpg`
- 静音轨道 `attribute=1`，片段 `volume=0`

## API 摘要

### DraftFolder

```go
folder, err := jianying.NewDraftFolder(folderPath, jianying.WithFFprobePath("ffprobe"))
folder.CreateDraftSimple(name, width, height, allowReplace)
folder.ListDrafts() / folder.HasDraft(name) / folder.RemoveDraft(name)
```

### ScriptFile

```go
script.AddTrack(trackType, trackName, jianying.WithMute(true), jianying.WithRelativeIndex(1))
script.AddVideoSegment(seg, trackName)
script.Save()    // 推荐：完整保存（素材库 + meta）
script.Dump(path) // 仅写 JSON，不同步素材面板
```

### 轨道类型

`TrackTypeVideo` · `TrackTypeAudio` · `TrackTypeText` · `TrackTypeEffect` · `TrackTypeFilter` · `TrackTypeSticker`

更多 API 见 [docs/api.md](docs/api.md)。

## 项目结构

```
com.linker.jianying.sdk/
├── assets/                 # draft_content / draft_meta 模板
├── docs/
│   ├── api.md
│   └── comparison.md       # 与 pyJianYingDraft 对照
├── example/01_basic/       # 素材面板 + 静音示例
├── draft_folder.go         # 草稿目录管理
├── draft_meta.go           # draft_materials 构建与 meta 同步
├── draft_cover.go          # ffmpeg 截取封面
├── material_store.go       # 素材库复制
├── paths.go                # 读取剪映 globalSetting
├── script_file.go          # 核心 Save / Dump 逻辑
├── track.go                # 轨道（含静音）
└── ...
```

## 剪映草稿路径

- **Windows 默认**: `C:\Users\{用户}\AppData\Local\JianyingPro\User Data\Projects\com.lveditor.draft`
- **macOS 默认**: `~/Movies/JianyingPro/User Data/Projects/com.lveditor.draft`
- 或在剪映设置 → 草稿位置 / 素材位置 中查看

## 测试

```bash
go test ./...
```

集成测试 `save_integration_test.go` 需要本地存在 `E:\demo\珀莱雅红宝石水乳面霜.mp4`，不存在时自动 skip。

## 文档

- [API 参考](docs/api.md)
- [与 pyJianYingDraft 对比](docs/comparison.md)
- [变更日志](CHANGELOG.md)

## 参考

- [pyJianYingDraft](https://github.com/GuanYixuan/pyJianYingDraft) — API 与草稿结构的主要参考
- [jianying-importer](../jianying-importer) — 素材库复制与 `draft_materials` 字段参考

## License

MIT License

com.linker.jianying.sdk

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README