com.linker.jianying.sdk

KO | EN

gitlite — search

#javascript #css #golang #html #react #python3 #machine-learning #go #python #template #typescript #nodejs

com.linker.jianying.sdk

★ 28 Open GitHub ↗

轻量、灵活的 Golang 剪映草稿生成工具，可以将本地视频文件批量导入到剪映草稿中。

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# JianYing Draft SDK for Go

轻量、灵活的 Golang 剪映草稿生成工具，可以将本地视频文件批量导入到剪映草稿中。

## 功能特性

- 创建和管理剪映草稿文件夹
- 将本地视频/图片文件导入到剪映草稿
- 支持自定义视频分辨率和帧率
- 支持视频片段的时间截取和变速播放
- 支持多轨道管理
- 使用命令行 ffprobe 获取媒体信息（路径可配置）

## 安装

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

## 依赖

- Go 1.22+
- FFmpeg（需要 ffprobe 命令行工具）

## 快速开始

### 基础用法

```go
package main

import (
    "fmt"
    "log"

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

func main() {
    // 1. 创建草稿文件夹管理器，传入 ffprobe 路径
    folder, err := jianying.NewDraftFolder(
        "C:/Users/xxx/JianyingPro Drafts",          // 剪映草稿文件夹路径
        jianying.WithFFprobePath("C:/ffmpeg/bin/ffprobe.exe"), // ffprobe 路径
    )
    if err != nil {
        log.Fatal(err)
    }

// 2. 创建新草稿 (1920x1080, 30fps)
    script, err := folder.CreateDraftSimple("my_draft", 1920, 1080, true)
    if err != nil {
        log.Fatal(err)
    }

// 3. 添加视频轨道
    script.AddTrack(jianying.TrackTypeVideo, "")

// 4. 添加视频文件
    material, _ := jianying.NewVideoMaterial("ffprobe", "video.mp4", "")
    seg, _ := jianying.NewVideoSegment(material, jianying.NewTimerange(0, material.Duration), nil)
    script.AddVideoSegment(seg, "")

// 5. 保存草稿
    if err := script.Save(); err != nil {
        log.Fatal(err)
    }

fmt.Println("草稿创建成功！")
}
```

### 批量导入多个视频

```go
func importMultipleVideos(folder *jianying.DraftFolder, ffprobePath string, videoFiles []string) error {
    // 创建草稿
    script, err := folder.CreateDraftSimple("batch_import", 1920, 1080, true)
    if err != nil {
        return err
    }

// 添加视频轨道
    script.AddTrack(jianying.TrackTypeVideo, "")

// 批量添加视频，视频会按顺序排列在时间轴上
    var currentTime int64 = 0
    for _, videoPath := range videoFiles {
        // 创建素材
        material, err := jianying.NewVideoMaterial(ffprobePath, videoPath, "")
        if err != nil {
            return err
        }

// 创建片段 - 使用素材的完整时长
        seg, err := jianying.NewVideoSegment(
            material,
            jianying.NewTimerange(currentTime, material.Duration),
            nil,
        )
        if err != nil {
            return err
        }

// 添加到轨道
        script.AddVideoSegment(seg, "")

// 更新时间位置
        currentTime = seg.End()
    }

return script.Save()
}
```

## API 文档

### DraftFolder - 草稿文件夹管理

```go
// 创建草稿文件夹管理器
folder, err := jianying.NewDraftFolder(folderPath, opts...)

// 可选配置
jianying.WithFFprobePath(path)  // 设置 ffprobe 可执行文件路径

// 方法
folder.ListDrafts()                              // 列出所有草稿
folder.HasDraft(name)                            // 检查草稿是否存在
folder.RemoveDraft(name)                         // 删除草稿
folder.CreateDraft(name, width, height, opts)    // 创建草稿（完整参数）
folder.CreateDraftSimple(name, width, height, allowReplace) // 创建草稿（简化）
folder.GetDraftPath(name)                        // 获取草稿路径
```

### ScriptFile - 草稿文件

```go
// 添加轨道
script.AddTrack(trackType, trackName, opts...)

// 轨道类型
jianying.TrackTypeVideo   // 视频轨道
jianying.TrackTypeAudio   // 音频轨道
jianying.TrackTypeText    // 文本轨道
jianying.TrackTypeEffect  // 特效轨道
jianying.TrackTypeFilter  // 滤镜轨道
jianying.TrackTypeSticker // 贴纸轨道

// 轨道选项
jianying.WithMute(true)           // 静音轨道
jianying.WithRelativeIndex(1)     // 相对层级

// 添加视频片段
script.AddVideoSegment(segment, trackName)

// 便捷方法：直接添加视频文件
script.AddVideoFile(filePath, timerange, trackName, opts)

// 保存
script.Save()         // 保存到创建时的路径
script.Dump(path)     // 保存到指定路径
script.Dumps()        // 导出为 JSON 字符串

// 属性
script.GetDuration()  // 获取总时长（微秒）
script.GetTrackCount() // 获取轨道数量
```

### VideoMaterial - 视频素材

```go
// 创建视频素材
material, err := jianying.NewVideoMaterial(ffprobePath, filePath, materialName)

// 属性
material.MaterialID   // 素材 ID
material.MaterialName // 素材名称
material.Path         // 文件路径
material.Duration     // 时长（微秒）
material.Width        // 宽度（像素）
material.Height       // 高度（像素）
material.MaterialType // 类型 ("video" 或 "photo")
```

### VideoSegment - 视频片段

```go
// 创建视频片段
seg, err := jianying.NewVideoSegment(material, targetTimerange, opts)

// 片段选项
opts := &jianying.VideoSegmentOptions{
    SourceTimerange: jianying.Trange("10s", "5s"), // 截取素材的指定部分
    Speed:           &speed,                        // 播放速度 (1.0 = 正常)
    Volume:          0.5,                           // 音量 (0.0-1.0)
    ChangePitch:     false,                         // 变速时是否改变音调
    ClipSettings:    clipSettings,                  // 图像调节设置
}

// 属性
seg.GetTargetTimerange() // 在轨道上的时间范围
seg.End()                // 结束时间
seg.GetSpeed()           // 播放速度
```

### Timerange - 时间范围

```go
// 时间常量
jianying.SEC  // 1秒 = 1000000微秒

// 创建时间范围
tr := jianying.NewTimerange(start, duration)  // 微秒
tr := jianying.Trange("0s", "5s")             // 字符串格式

// 解析时间字符串
us := jianying.Tim("1h2m3s")   // 转换为微秒
us := jianying.Tim("1.5s")     // 支持小数
us := jianying.Tim("-0.5s")    // 支持负数

// 格式化时长
str := jianying.FormatDuration(us)  // 微秒转为可读字符串

// 属性和方法
tr.Start     // 起始时间
tr.Duration  // 持续时长
tr.End()     // 结束时间
tr.Overlaps(other)  // 检查是否重叠
```

### ClipSettings - 图像调节设置

```go
// 创建默认设置
settings := jianying.NewDefaultClipSettings()

// 或自定义设置
settings := &jianying.ClipSettings{
    Alpha:          1.0,   // 不透明度 (0.0-1.0)
    FlipHorizontal: false, // 水平翻转
    FlipVertical:   false, // 垂直翻转
    Rotation:       0.0,   // 旋转角度
    ScaleX:         1.0,   // X轴缩放
    ScaleY:         1.0,   // Y轴缩放
    TransformX:     0.0,   // X轴位移（半画布宽为单位）
    TransformY:     0.0,   // Y轴位移（半画布高为单位）
}
```

## 项目结构

```
├── assets/
│   ├── assets.go                  # 嵌入资源文件
│   ├── draft_content_template.json
│   └── draft_meta_info.json
├── draft_folder.go                # 草稿文件夹管理
├── script_file.go                 # 草稿文件核心逻辑
├── material.go                    # 视频素材（ffprobe 集成）
├── segment.go                     # 视频片段
├── track.go                       # 轨道管理
├── timerange.go                   # 时间工具
├── types.go                       # 公共类型定义
├── example/
│   └── main.go                    # 使用示例
├── go.mod
└── README.md
```

## 剪映草稿路径

剪映专业版的默认草稿路径：

- **Windows**: `C:\Users\{用户名}\AppData\Local\JianyingPro\User Data\Projects\com.lveditor.draft`
- 或在剪映设置中查看"草稿位置"

## FFprobe 配置

本 SDK 使用 ffprobe 命令行工具获取视频元信息。你需要：

1. 下载安装 [FFmpeg](https://ffmpeg.org/download.html)
2. 在创建 `DraftFolder` 时指定 ffprobe 路径：

```go
// 方式1：指定完整路径
folder, _ := jianying.NewDraftFolder(
    draftPath,
    jianying.WithFFprobePath("C:/ffmpeg/bin/ffprobe.exe"),
)

// 方式2：如果 ffprobe 在系统 PATH 中，可以直接使用
folder, _ := jianying.NewDraftFolder(
    draftPath,
    jianying.WithFFprobePath("ffprobe"),
)
```

## 注意事项

1. **剪映版本兼容性**：本 SDK 生成的草稿文件适用于剪映专业版 5.x 及以上版本
2. **主轨道限制**：最底层视频轨道上的片段必须从 0s 开始，否则会被剪映强制对齐
3. **草稿刷新**：创建草稿后可能需要重启剪映或切换页面来刷新草稿列表
4. **文件路径**：视频文件路径会被转换为绝对路径存储

## 实现范围

当前版本实现的功能：
- ✅ 创建/管理草稿文件夹
- ✅ 视频/图片素材导入
- ✅ 视频轨道管理
- ✅ 视频片段（时间截取、变速）
- ✅ 图像调节设置

暂未实现：
- ❌ 音频素材和轨道
- ❌ 文本/字幕
- ❌ 特效/滤镜/转场
- ❌ 动画/关键帧
- ❌ 模板模式
- ❌ 自动导出

## 参考

本项目参考了 Python 版本的实现：[pyJianYingDraft](https://github.com/GuanYixuan/pyJianYingDraft)

## License

MIT License

com.linker.jianying.sdk

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README