# jianying-draft-exporter

**Repository Path**: AICodeOS/jianying-draft-exporter

## Basic Information

- **Project Name**: jianying-draft-exporter
- **Description**:  一个剪映草稿自动化导出系统，支持自动下载网络草稿并导出为视频文件。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-30
- **Last Updated**: 2025-12-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DraftExport - 剪映草稿自动化模块

## 功能概述

DraftExport 提供完整的剪映草稿自动化功能，支持：

1. **剪映小助手自动化** - 支持两种下载方式
   - **开源剪映小助手**（推荐）- 使用HTTP直接下载，更稳定
   - **速推剪映小助手** - 使用UI自动化模拟点击下载
2. **剪映导出自动化** - 自动导出本地草稿
3. **完整工作流程** - 下载→导出一体化流程
4. **HTTP API服务** - 提供Web接口调用

## 模块结构

```
DraftExport/
├── __init__.py                              # 模块初始化
├── jianying_helper_controller.py            # 速推剪映小助手控制器（UI自动化）
├── opensource_jianying_helper_controller.py # 开源剪映小助手控制器（HTTP下载）
├── export_controller.py                     # 剪映导出控制器
├── workflow_manager.py                      # 工作流管理器
├── draft_automation_service.py              # HTTP API服务
├── config.json                              # 配置文件
└── README.md                                # 本文档
```

## 下载方式说明

### 开源剪映小助手（默认，推荐）

- **实现方式**: 直接通过HTTP请求下载草稿文件
- **优势**:
  - 无需UI自动化，更稳定可靠
  - 下载速度更快
  - 不受窗口操作影响
- **使用场景**: 推荐作为默认方式使用

### 速推剪映小助手

- **实现方式**: 使用UI自动化模拟点击剪映小助手窗口
- **特点**:
  - 需要剪映小助手窗口可见
  - 依赖UI控件查找
- **使用场景**: 作为备用方式，当HTTP方式不可用时使用

## 系统要求

### 软件依赖
- Python 3.8+
- 剪映专业版（建议6.x或以下版本，支持UI自动化）
- 剪映小助手（用于下载网络草稿）

### Python包依赖
```bash
pip install flask flask-cors pywin32 uiautomation pyperclip requests
```

### 系统要求
- Windows 操作系统
- 已安装并配置好剪映专业版
- 可选：剪映小助手（使用速推方式时需要）

## 快速开始

### 1. 基本使用

```python
from DraftExport import WorkflowManager, ExportResolution, ExportFramerate, HelperType

# 创建工作流管理器（默认使用开源小助手）
workflow = WorkflowManager()

# 或者明确指定使用开源小助手
workflow = WorkflowManager(helper_type=HelperType.OPENSOURCE)

# 或者使用速推小助手
# workflow = WorkflowManager(helper_type=HelperType.SUTUI)

# 执行完整流程：下载 + 导出
result = workflow.execute_workflow(
    url="https://example.com/jianying-draft-url",
    output_path="C:/exports/my_video.mp4",
    resolution=ExportResolution.RES_1080P,
    framerate=ExportFramerate.FR_30
)

if result['status'] == 'completed':
    print(f"成功！文件位置: {result['result']['final_path']}")
else:
    print(f"失败: {result['message']}")
```

### 2. 指定下载方式

```python
from DraftExport import WorkflowManager, HelperType

workflow = WorkflowManager()

# 使用开源小助手下载
result = workflow.execute_workflow(
    url="https://example.com/draft",
    helper_type=HelperType.OPENSOURCE
)

# 使用速推小助手下载
result = workflow.execute_workflow(
    url="https://example.com/draft",
    helper_type=HelperType.SUTUI
)
```

### 3. HTTP API 服务

```python
from DraftExport import DraftAutomationService

# 启动HTTP服务
service = DraftAutomationService()
service.run(host='0.0.0.0', port=5000)
```

## API 接口文档

### 完整流程接口

**POST** `/api/process-draft`

下载草稿并导出为视频文件。

**请求参数:**
```json
{
    "url": "https://example.com/draft-url",
    "output_path": "C:/exports/video.mp4",
    "draft_name": "我的草稿",
    "resolution": "1080P",
    "framerate": "30fps",
    "helper_type": "opensource"
}
```

**参数说明:**
- `helper_type`: 可选，下载方式，可选值：
  - `opensource`: 开源剪映小助手（默认，推荐）
  - `sutui`: 速推剪映小助手

**响应示例:**
```json
{
    "status": "completed",
    "message": "任务完成",
    "progress": 100.0,
    "result": {
        "success": true,
        "final_path": "C:/exports/video.mp4"
    }
}
```

### 异步任务接口

**POST** `/api/start-task`

启动异步任务。

**GET** `/api/task-status/<task_id>`

获取任务状态。

**GET** `/api/tasks`

获取所有任务列表。

### 单独功能接口

**POST** `/api/download-draft`

仅下载草稿。可指定 `helper_type` 参数选择下载方式。

**请求参数:**
```json
{
    "url": "https://example.com/draft-url",
    "helper_type": "opensource"
}
```

**POST** `/api/export-draft`

仅导出草稿。

### 系统接口

**GET** `/api/health`

系统健康检查。

**POST** `/api/cleanup`

清理已完成的任务。

## 配置说明

### 配置文件 (config.json)

```json
{
  "helper_type": "opensource",
  "helpers": {
    "sutui": {
      "enabled": true,
      "name": "速推剪映小助手",
      "description": "使用UI自动化模拟点击下载草稿",
      "timeout": 180
    },
    "opensource": {
      "enabled": true,
      "name": "开源剪映小助手",
      "description": "使用HTTP直接下载草稿文件",
      "timeout": 120,
      "target_directory": ""
    }
  }
}
```

### 下载方式配置

- `helper_type`: 默认使用的下载方式（`opensource` 或 `sutui`）
- `helpers.sutui`: 速推剪映小助手配置
- `helpers.opensource`: 开源剪映小助手配置

### 分辨率选项
- `8K`, `4K`, `2K`, `1080P`, `720P`, `480P`

### 帧率选项
- `24fps`, `25fps`, `30fps`, `50fps`, `60fps`

## 使用示例

### 1. 完整流程
```bash
# 使用默认方式（开源小助手）
curl -X POST http://localhost:5000/api/process-draft \
     -H "Content-Type: application/json" \
     -d '{"url": "https://example.com/draft", "output_path": "C:/exports/"}'

# 指定使用速推小助手
curl -X POST http://localhost:5000/api/process-draft \
     -H "Content-Type: application/json" \
     -d '{"url": "https://example.com/draft", "output_path": "C:/exports/", "helper_type": "sutui"}'
```

### 2. 异步任务
```bash
# 启动任务
curl -X POST http://localhost:5000/api/start-task \
     -H "Content-Type: application/json" \
     -d '{"url": "https://example.com/draft", "task_id": "my_task"}'

# 查看状态
curl http://localhost:5000/api/task-status/my_task
```

### 3. 分步执行
```bash
# 下载草稿（使用开源小助手）
curl -X POST http://localhost:5000/api/download-draft \
     -H "Content-Type: application/json" \
     -d '{"url": "https://example.com/draft", "helper_type": "opensource"}'

# 下载草稿（使用速推小助手）
curl -X POST http://localhost:5000/api/download-draft \
     -H "Content-Type: application/json" \
     -d '{"url": "https://example.com/draft", "helper_type": "sutui"}'

# 导出草稿
curl -X POST http://localhost:5000/api/export-draft \
     -H "Content-Type: application/json" \
     -d '{"draft_name": "我的草稿", "output_path": "C:/exports/video.mp4"}'
```

## 错误处理

### 常见错误

#### 开源剪映小助手相关
1. **获取文件列表失败** - 检查URL是否有效，网络是否正常
2. **下载文件失败** - 检查网络连接，确认有足够的磁盘空间
3. **路径修改失败** - 检查草稿目录权限

#### 速推剪映小助手相关
1. **未找到剪映小助手窗口** - 确保剪映小助手已启动
2. **控件查找失败** - 尝试重启剪映小助手
3. **UI自动化超时** - 检查窗口是否被其他程序遮挡

#### 导出相关
1. **未找到剪映主程序窗口** - 确保剪映专业版已启动并在主页
2. **导出失败** - 检查草稿是否存在，是否有导出权限
3. **UIAutomation库不可用** - 确保已安装 `uiautomation` 包

### 日志输出
程序会输出详细的日志信息，包括：
- 窗口查找过程
- 控件操作步骤
- 任务执行进度
- 错误详情

## 注意事项

1. **下载方式选择**
   - **推荐使用开源剪映小助手**（HTTP下载方式）：更稳定、更快速
   - 速推剪映小助手作为备用方式

2. **剪映版本兼容性**
   - 开源剪映小助手：支持所有版本
   - 速推剪映小助手：支持各版本
   - 导出功能：建议使用剪映6.x及以下版本

3. **系统权限**
   - 需要UI自动化权限（使用速推方式时）
   - 确保有文件系统读写权限

4. **窗口操作**
   - 使用速推方式时，剪映窗口会被置顶
   - 开源方式无需窗口操作

5. **网络要求**
   - 下载草稿需要网络连接
   - 某些草稿可能需要登录状态

## 开发和扩展

### 添加新功能
1. 在相应的控制器中添加方法
2. 在工作流管理器中集成
3. 在HTTP服务中添加对应接口

### 自定义配置
可以通过继承现有类来自定义行为：

```python
from DraftExport import WorkflowManager

class CustomWorkflowManager(WorkflowManager):
    def _wait_for_draft(self, task, max_wait_time=120.0):
        # 自定义草稿检测逻辑
        pass
```

## 故障排除

### 1. 开源小助手HTTP下载失败
- 检查网络连接是否正常
- 确认URL格式正确
- 检查是否有防火墙阻止
- 尝试切换到速推小助手方式

### 2. 速推小助手UI自动化失败
- 检查剪映小助手窗口是否可见
- 尝试重启剪映小助手程序
- 检查Windows UAC设置
- 尝试切换到开源小助手方式

### 3. 网络草稿下载失败
- 确认URL有效性
- 检查网络连接
- 验证草稿是否已过期

### 4. 导出超时
- 增加超时时间设置
- 检查系统性能
- 确认有足够的磁盘空间

## 更新日志

### v1.1.0 (最新)
- 新增开源剪映小助手支持（HTTP下载方式）
- 新增 `HelperType` 枚举，支持两种下载方式切换
- 优化配置文件结构，支持多种小助手配置
- 更新API接口，支持 `helper_type` 参数
- 默认使用开源小助手（更稳定）

### v1.0.0
- 初始版本发布
- 支持完整的下载和导出流程
- 提供HTTP API接口
- 支持异步任务管理