# clipforge

**Repository Path**: nhitinga/clipforge

## Basic Information

- **Project Name**: clipforge
- **Description**: base: import MoneyPrinterTurbo v1.3.5 fixed version
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-25
- **Last Updated**: 2026-09-20

## Categories & Tags

**Categories**: multimedia

**Tags**: None

## README

<div align="center">

# clipforge ✂️

### AI 短视频生成 SaaS 服务

面向中国大陆用户的短视频生成 SaaS 网关：**不自建用户/账号/计费系统**，以 `app_key + sign` 签名接入外部客户系统（ldbsrv 统一用户中心）；任务入队 → 独立 worker 渲染 → 回调结果。**模型全部本地预置，运行期零网络下载**。

</div>

---

## 工程概览

| 层 | 说明 |
|---|---|
| `saas_gateway/` | FastAPI SaaS 网关（:8090）：任务签名鉴权 / 三级租户隔离（全局→app_key→用户）/ 任务队列与并发配额 / 回调重试 / 监控清理 / OSS 成片上传 |
| `frontend/` | Vue 3 + Element Plus 控制台（网关 `/console` 托管）：任务/成片/用户/素材管理，三入口登录（admin/customer/user，对接 ldbsrv JWT） |
| `app/` | 视频渲染内核（源自 MoneyPrinterTurbo）：脚本→素材→配音→字幕→合成 |
| `models/` | 本地模型（不入库、不打包镜像）：whisper ASR + Piper/Kokoro onnx TTS |
| `docker/` | SaaS 镜像构建（模型卷挂载，镜像精简） |

**对接文档**：[系统设计文档](docs/系统设计文档.md) · [外部系统对接协议](docs/api-protocol.md) · [外部网络调用清单](docs/external-network-list.md) · [本地 ASR/TTS 实现总结](docs/architecture/local-asr-and-tts.md) · [本地 TTS 模型说明](docs/models/local-tts-models.md) · [Docker 打包与部署](docs/docker-deployment.md)

## 本地语音（ASR + TTS）

全部 **onnxruntime CPU 推理**，免 API key、免联网：

- **ASR**：`faster-whisper`（small / large-v3）— 字幕时间轴 + 草稿/爆款理解
- **TTS `piper:`**：中文 3 音色（华研·女声 / 晓雅·女声 / 朝文·男声），极快
- **TTS `kokoro:`**：中文 103 音色（zf 女 / zm 男），**misaki 注音音素**产出地道普通话
- 云端 provider（edge / azure / siliconflow / minimax / elevenlabs 等）依旧并存，`config.toml [app] tts_provider` 切换

测试与批量工具：

```bash
python tools/test_tts.py --model kokoro --voice zf_001 "你好，测试"
python tools/test_tts.py --model kokoro --show-voice    # 103 音色+中文名+特点
```

## 快速开始（本地 · 开发调试）

```bash
conda activate music
python download-models.py --small         # 预下载 whisper（断点续传；生产用 --large-v3）
./start.sh                                # 前台调试：网关 :8090 + worker + 前端 vite(5173)，Ctrl+C 全停
./start.sh --ldbsrv                       # 服务器模式：SSH 隧道连 ldbsrv 的 Redis/MySQL
./start.sh --no-ui                        # 只跑后端，不起前端 vite
./start.sh logs                           # 前台滚动看日志（不改变启动方式）
```

## Docker 部署（docker.sh · 正式）

模型**不打包进镜像**，由 `docker-compose.saas.yml` 卷挂载宿主机 `./models/` → 容器 `/app/models:ro`。启动前务必先下载模型到 `./models/`。**Redis / MySQL 也走宿主机**（`host.docker.internal`），配置在 `.env.docker`（参考 `.env.docker.example`）。**上传素材/任务产物(/app/storage)绑定宿主机 `./storage`**，换版本不丢。

```bash
cp .env.docker.example .env.docker   # 首次：按需改 Redis/MySQL 地址与密码
./docker.sh --build --ver 0.4.0      # 构建镜像 clipforge:0.4.0
./docker.sh --start  --ver 0.4.0     # 启动（版本缺省则自动/交互选择；不重建）
./docker.sh --stop   --ver 0.4.0     # 停止并移除服务
./docker.sh --status                 # 列出已发布镜像版本
./docker.sh --log                    # 跟踪运行日志（未启动会提示）
```

> ⚠️ `start.sh`（本地调试）与 `docker.sh`（正式）配置文件互不影响：前者用 `.env`，后者用 `.env.docker`。
> ⚠️ 项目外的 Docker 配置（`~/.docker/daemon.json` 镜像加速）易遗漏，部署服务器前必配，见 [Docker 打包与部署](docs/docker-deployment.md)。

### 任务进度实时推送（SSE）

任务列表用 **SSE**（`/clipforge/api/v1/task/events`）实时推送状态/进度变更，替代前端定时轮询：

- worker 每次 `patch_task`（状态/进度变化）经 Redis pub/sub 广播 `task_update`，网关推送给在线控制台。
- 前端用 `fetch` 流带 JWT 读取，按 `task_id` 就地回填进度，无需整页刷新；断线自动退避重连。
- 任务列表**支持删除**：`pending`/`failed`/`success` 均可删除（`running` 禁止），删除同步清理 Redis 状态、MySQL 记录与工作目录。


### 安装 Docker（如未安装）

macOS（Homebrew）：

```bash
brew install --cask docker     # 安装 Docker Desktop
open -a Docker                 # 启动一次，按提示完成授权
docker --version               # 验证
```

Linux（Ubuntu/Debian，官方脚本）：

```bash
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER && newgrp docker
docker compose version
```

> 中国大陆网络可配置镜像加速（Docker Desktop → Settings → Docker Engine 添加 `registry-mirrors`，或云厂商加速地址）。

## 配置

运行配置 `config.toml`（不入库；从 `config.example.toml` 生成）。关键段：

```toml
[app]
tts_provider = "piper"     # edge / piper / kokoro / siliconflow / ...

[whisper]
model_size = "small"       # 生产建议 large-v3

[piper] / [kokoro]         # 本地 TTS 模型目录与音色（留空自动扫描 models/）
```

鉴权与租户环境变量见 `docker-compose.saas.yml`（`CLIPFORGE_APP_KEYS`、MySQL/OSS 等）。

## 目录速览

```
saas_gateway/   # SaaS 网关（FastAPI）
frontend/       # Vue3 控制台（dist 由网关托管）
app/            # 渲染内核（MoneyPrinterTurbo）
models/         # 本地模型（git 忽略、镜像不打包）
  ├─ whisper-small|large-v3/    # ASR
  ├─ piper/zh/zh_CN/...         # TTS 中文 3 音色
  └─ kokoro-zh/onnx/            # TTS 中文 103 音色
docs/           # 设计/协议/实现文档
tools/          # TTS 测试与模型转换工具
docker/         # SaaS Dockerfile + entrypoint
```

---

## 分支说明

- **`main`**：主开发分支，当前所有成果（SaaS 网关、Vue 控制台、本地 ASR/TTS、Docker 部署、用户中心改造）都已合并到这里，**后续开发从 `main` 进行**。
- **`dev`**：历史开发分支，现已并入 `main`，**保留作为备份**（不再作为开发主线）。
- **`upstream/original`**：上游 MoneyPrinterTurbo 完整代码保留。

> 已移除上游 Streamlit WebUI（`webui/`），界面统一使用 Vue 控制台（网关 `/console` 托管）。

## 来源与许可

本项目的视频渲染内核源自开源项目 [MoneyPrinterTurbo](https://github.com/harry0703/MoneyPrinterTurbo)（作者 harry0703），在其基础上构建了完整的 SaaS 网关、控制台、租户体系与本地语音能力，在此致谢。

- 上游原版 readme 见 [main 分支](https://gitee.com/nhitinga/clipforge/tree/main)（`upstream/original` 分支保留完整上游代码）
- 许可证：[MIT](LICENSE)（上游 Copyright (c) 2024 Harry 的 MIT 声明继续适用）