# ai-cut

**Repository Path**: JoinXin/ai-cut

## Basic Information

- **Project Name**: ai-cut
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-23
- **Last Updated**: 2026-04-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ShortGPT Render

将 **OpenTimelineIO（OTIO）JSON** 时间线渲染为 MP4：基于 MoviePy + FFmpeg，支持 `metadata.shortgpt` 贴纸与字幕（见 `examples/sample_edit_json_fields.md` 与 `智能剪辑otto文件格式设计.md`）。

| 示例 JSON | 说明 |
|-----------|------|
| `examples/sample_edit.json` | 含 `metadata.shortgpt`，与当前渲染器行为一致（见 `sample_edit_json_fields.md`）。 |
| `examples/otto_design_sample.json` | **新设计规范**：根级 `metadata.version/canvas/output`、轨道 `layer_type`（主视频 / 贴纸 / 字幕 / BGM / SFX）、`Transition.dissolve`、`MissingReference` 字幕片段。由 `python examples/build_otto_design_sample.py` 根据 `examples/clips` 与 `test_resoucess` 重新生成。 |

当前 `OtioMoviePyBridge` 对 **V2 贴纸轨**（PNG `ExternalReference`）会参与合成；**V3 字幕轨**（`MissingReference` + `metadata.text`）尚需在桥接层按设计文档实现栅格化，现阶段该轨在画面上可能表现为空隙/黑场，仅供结构与解析测试。

---

## 环境要求

- Python **3.10+**
- 已安装 **FFmpeg**（在 `PATH` 中可执行 `ffmpeg`）
- 可选：NVIDIA 驱动 + 支持 NVENC 的 FFmpeg（环境变量 `SHORTGPT_NVENC=1`）

---

## 安装

在项目根目录（本仓库）执行：

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -U pip
pip install -e ".[api,dev]"
```

说明：

- 核心依赖在默认 `dependencies` 中；**HTTP API** 需额外安装 **`[api]`**（FastAPI、Uvicorn）。
- **`[dev]`**：pytest、ruff 等，仅开发需要。

---

## CLI：渲染命令

```powershell
# 默认示例：examples/sample_edit.json → examples/sample_edit_out.mp4
shortgpt-render render

# 指定 JSON 与输出
shortgpt-render render path\to\edit.json path\to\out.mp4

# 档位：draft / fast / quality
shortgpt-render render examples\sample_edit.json out.mp4 -q draft

# 写入渲染清单（成片仍全量；真增量见技术设计方案）
shortgpt-render render --incremental

# 低分辨率代理预览
shortgpt-render proxy examples\sample_edit.json proxy_out.mp4

# Gap 管线演示
shortgpt-render gap-demo

# 清空本地渲染缓存目录 .render_cache
shortgpt-render clear-cache
```

兼容旧入口（等价于调用包内桥接）：

```powershell
python test_render.py
python test_render.py examples\sample_edit.json out.mp4
```

---

## HTTP API：启动与调用

### 1. 启动服务

```powershell
cd E:\ttt\shortGpt
.\.venv\Scripts\Activate.ps1
shortgpt-api
```

默认监听 **`http://127.0.0.1:8765`**。

浏览器打开 **`http://127.0.0.1:8765/`** 可进入 **文档导航页**（Swagger / ReDoc / RapiDoc / OpenAPI JSON）。

### 2. 环境变量（可选）

| 变量 | 说明 | 默认 |
|------|------|------|
| `SHORTGPT_API_HOST` | 绑定地址 | `127.0.0.1` |
| `SHORTGPT_API_PORT` | 端口 | `8765` |
| `SHORTGPT_API_RELOAD` | `1` / `true` 开启热重载（开发） | 关 |
| `SHORTGPT_API_CORS_ORIGINS` | 逗号分隔的允许源；不设则放行常见本地前端端口 | 见下 |
| `SHORTGPT_API_PUBLIC_BASE` | 无尾斜杠的对外根 URL，如 `http://127.0.0.1:8765` | 空（OpenAPI 使用相对路径） |

未设置 `SHORTGPT_API_CORS_ORIGINS` 时，默认允许：`http://127.0.0.1:5173`、`http://localhost:5173`、`http://127.0.0.1:3000`、`http://localhost:3000`。

### 3. 等价启动方式（Uvicorn）

```powershell
uvicorn shortgpt_render.api.app:create_app --factory --host 127.0.0.1 --port 8765
```

开发热重载：

```powershell
$env:SHORTGPT_API_RELOAD = "1"
shortgpt-api
```

### 4. 接口与文档页面

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/` | **文档导航**（链到下列各页） |
| `GET` | `/docs` | **Swagger UI**（FastAPI 内置，Try it out） |
| `GET` | `/redoc` | **ReDoc**（长文档阅读） |
| `GET` | `/rapidoc` | **RapiDoc**（三栏 + 暗色，依赖 jsDelivr CDN） |
| `GET` | `/openapi.json` | OpenAPI 3 规范原文 |
| `GET` | `/health` | 健康检查 |
| `POST` | `/render` | 同步渲染（请求体内为绝对路径，见下） |

反代或需固定「Try it out」请求地址时，设置 `SHORTGPT_API_PUBLIC_BASE`（见上表）。

**`POST /render` 请求体（JSON）**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `json_path` | string | 是 | OTIO JSON 的**绝对路径**（服务端进程可读） |
| `output_path` | string | 是 | 输出 MP4 的**绝对路径**（父目录会自动创建） |
| `project_root` | string | 否 | 解析 `target_url` 相对路径的根目录；默认当前工作目录 |
| `quality` | string | 否 | `draft` / `fast` / `quality`，默认 `fast` |
| `incremental` | bool | 否 | 是否更新 manifest；默认 `false` |

**注意**：`/render` 为 **同步阻塞**，成片较长时会占用请求直到编码结束。生产环境建议改为任务队列 + 轮询/WebSocket 进度（见 `技术设计方案.md`）。

### 5. 调用示例（PowerShell）

将路径换成你本机实际绝对路径：

```powershell
# 健康检查
Invoke-RestMethod -Uri "http://127.0.0.1:8765/health" -Method Get

# 触发渲染（路径请改为你的仓库根下的真实路径）
$body = @{
  json_path   = "E:\ttt\shortGpt\examples\sample_edit.json"
  output_path = "E:\ttt\shortGpt\examples\api_render_out.mp4"
  project_root = "E:\ttt\shortGpt"
  quality     = "fast"
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://127.0.0.1:8765/render" -Method Post -Body $body -ContentType "application/json"
```

使用 **curl**（Windows 自带或 Git Bash）：

```bash
curl -s http://127.0.0.1:8765/health

curl -s -X POST http://127.0.0.1:8765/render ^
  -H "Content-Type: application/json" ^
  -d "{\"json_path\":\"E:/ttt/shortGpt/examples/sample_edit.json\",\"output_path\":\"E:/ttt/shortGpt/examples/api_render_out.mp4\",\"project_root\":\"E:/ttt/shortGpt\",\"quality\":\"fast\"}"
```

---

## 测试

```powershell
pytest tests -q
```

---

## 文档

- 剪辑 JSON 字段与渲染行为：`examples/sample_edit_json_fields.md`
- OTIO 扩展与完整规范：`智能剪辑otto文件格式设计.md`
- 增量渲染、预览与工程路线：`技术设计方案.md`