com.linker.jianying.sdk

KO | EN

gitlite — search

#javascript #typescript #llm #golang #go #machine-learning #deep-learning #linux #docker #macos #java #cli #pytorch #open-source

com.linker.jianying.sdk

(★ 28)

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

com.linker.jianying.sdk Latest Version Download

Download Latest Version (.zip)

// 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

com.linker.jianying.sdk Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

com.linker.jianying.sdk

com.linker.jianying.sdk Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README