输入一个主题,产出一条可预览、可审核的中文短视频。跑在你自己的电脑或服务器上。
HotFactory 是单人使用、自托管的 AI 短视频生产工作站:把「主题 → 结构化脚本与分镜 → 动态画面与配音 → 成片质检 → 人工审核」串成一条可重复运行的流水线。默认用 Remotion 渲染暗色 SVG 动态信息图,也可切换 MoneyPrinterTurbo 兼容模式,产出带中文配音与字幕的口播片。
不做无人值守发布:AI 负责生产,成片是否发布始终由人确认。
快速开始 · 架构设计 · 运行手册 · 进度台账 · 报告问题
- 零 API Key 即可跑通:默认
fake脚本 +remotion引擎,不依赖模型 Key、素材库、外部数据库或 Docker;准备好本地 Edge TTS 后,装完就能出一条带配音的 MP4 验证整条链路。 - 能力可替换:LLM(fake / DeepSeek / SenseNova)与视频引擎(remotion / mpt / mock)统一收敛到
providers/,配置切换,业务代码不依赖服务商 SDK。 - 状态可追溯:SQLite 任务表 + 独立 Worker 原子认领,进度落库,刷新页面不丢状态,失败可重试。
- 人工把关:脚本落盘可手改复用,成片可预览、审核通过或驳回删除。
- 批量可复现:一条命令跑主题清单,每条独立成片并生成汇总报告。
- 单机自托管:SQLite 单文件即整库备份;生产机只需拉两个 Docker 镜像,不需要数据库服务、消息队列或 GPU。
一条视频的链路如下;设置 HF_VIDEO_PROVIDER=mpt 时,画面、配音、字幕与合成改由 MoneyPrinterTurbo 一次完成:
flowchart LR
A[主题 + 内容] --> B[LLM 结构化脚本 / 分镜]
B --> C[Remotion 动态画面]
C --> D[Edge TTS 旁白 + FFmpeg 封装]
D --> E[ffprobe 基础质检]
E --> F[人工预览 / 审核]
| 依赖 | 要求 |
|---|---|
| Python | 3.12+(后端与 Worker;推荐用 uv 建虚拟环境) |
| Node.js | 22+(前端构建、Remotion 渲染) |
| FFmpeg / ffprobe | 任意较新版本,需在 PATH 中(音轨封装与质检) |
| Edge TTS CLI | Remotion 模式用它生成旁白:默认读 .mpt-venv/Scripts/edge-tts.exe,可用 HF_MPT_TTS_COMMAND 指向任意可执行文件;Docker 镜像已内置 |
| npm | 随 Node 安装 |
不需要:API Key、外部数据库、Redis / 消息队列、GPU、Docker(本机试跑)、MoneyPrinterTurbo 服务(默认 Remotion 引擎)。只想验证任务链路时,把 HF_VIDEO_PROVIDER 设为 mock 可用测试图出片,连 Edge TTS 也不需要。
双击项目根目录的 start.bat,或在终端执行:
start.bat脚本依次完成:检查 Python / Node / FFmpeg 与端口 → 缺 config/.env 时从样例生成(默认 fake + remotion,不需要任何 Key)→ 安装依赖(含 video-renderer)→ 构建前端 → 启动后台 Worker → 启动 FastAPI 并打开浏览器。
访问 http://127.0.0.1:8000(前端由 FastAPI 单端口托管),接口文档在 /docs;在启动窗口按 Ctrl+C 停止,Worker 一并退出。常用参数:
| 参数 | 作用 |
|---|---|
-WithEngine |
HF_VIDEO_PROVIDER=mpt 时顺带启动 8080 引擎 |
-Dev |
前端 vite 热更新,访问 http://127.0.0.1:5173 |
-Rebuild / -Port 8010 |
强制重建前端 / 换端口 |
-SkipWorker / -NoBrowser / -Help |
只起 Web / 不自动开浏览器 / 查看全部参数 |
首次出片前准备旁白 CLI(宿主直跑只需一次;Docker 镜像已内置):
python -m venv .mpt-venv
.mpt-venv\Scripts\python.exe -m pip install edge-ttsLinux / macOS 用 .mpt-venv/bin/edge-tts,并把 config/.env 的 HF_MPT_TTS_COMMAND 指向它。缺少它时 Remotion 模式会报「找不到 Edge TTS」;只想验证任务链路,可临时把 HF_VIDEO_PROVIDER 设为 mock。
改了 config/.env 或后端代码后重跑 start.bat 即可(Worker 的配置与代码在启动时读入内存)。日志都在 logs/。
git clone https://github.com/999bug/HotFactory.git
cd HotFactory
# 1. 后端依赖与配置
cd backend
uv venv .venv --python 3.12
uv pip install -r requirements.txt
cd ..
cp config/env.example config/.env
# 2. 前端与渲染器依赖
(cd frontend && npm install && npm run build)
(cd video-renderer && npm install)
# 3. 起两个进程(各占一个终端)
cd backend
. .venv/bin/activate # Windows 用 .venv/Scripts/activate
python -m uvicorn app.main:app --port 8000
python -m app.workers # 另一个终端浏览器打开 http://127.0.0.1:8000;开发前端时改为 cd frontend && npm run dev(5173,/api 代理到 8000)。宿主直跑同样要按上一节准备 Edge TTS CLI,Linux / macOS 把 HF_MPT_TTS_COMMAND 指向 .mpt-venv/bin/edge-tts。
生产机只拉 GHCR 上的 hot-factory-web / hot-factory-worker 两个镜像,不需要装 Node / Python / FFmpeg,镜像内也已备好 Edge TTS 与中文字体:
sudo mkdir -p /opt/hotfactory && sudo chown "$USER" /opt/hotfactory
git clone https://github.com/999bug/HotFactory.git /opt/hotfactory
cd /opt/hotfactory
cp deploy.env.example deploy.env
cp config/env.example config/.env
bash scripts/docker-deploy.sh # pull → up -d → 等 healthy → 校验 build_version升级用 bash scripts/docker-update.sh(可加版本号或 --dry-run),回滚只需把 deploy.env 的 HF_IMAGE_TAG 改回上一版再跑一次部署脚本。校验:curl http://127.0.0.1:8000/api/health 返回的 build_version 应等于配置的镜像 tag。
镜像发布由推 v* tag 触发 GitHub Actions,只推 GHCR、无需配置任何 secret。镜像与部署的完整手册见 docs/runbook/docker-deploy-upgrade.md。
打开页面填一个主题 → 点「生成视频」→ 等待状态变为 WAITING_REVIEW → 预览成片;成片落在 output/videos/{task_id}/。也可以直接用 API:
curl -X POST http://127.0.0.1:8000/api/tasks \
-H "Content-Type: application/json" \
-d '{"topic":"一杯手冲咖啡的冲泡过程"}'
curl http://127.0.0.1:8000/api/tasks/<上一步返回的 id>
⚠️ 安全提示:系统没有登录认证,容器默认监听0.0.0.0。任何能访问该端口的人都能提交任务、消耗你的模型额度并写满磁盘。公网部署前至少做一件事:安全组只放行自己的 IP、改回127.0.0.1走ssh -L,或前置反代做 TLS + Basic Auth。MoneyPrinterTurbo 的 8080 端口一律只监听本机。
两个 env 文件分工固定,不要混用:
| 文件 | 管什么 | 典型键 |
|---|---|---|
config/.env(样例 config/env.example) |
应用配置:LLM provider / Key / model、视频引擎、Worker 参数 | HF_LLM_PROVIDER、HF_VIDEO_PROVIDER、HF_DEEPSEEK_API_KEY |
deploy.env(样例 deploy.env.example) |
compose 插值与部署参数:镜像 tag、端口、UID/GID、容器内引擎地址 | HF_IMAGE_TAG、HF_WEB_PORT、HF_MPT_API_BASE |
compose 注入的进程环境变量优先级高于 config/.env 的同名键(容器里四个路径键固定为 /hotfactory/*,HF_MPT_API_BASE 取 deploy.env);手写 compose 命令必须带 --env-file deploy.env。改 config/.env 后需重启 Web 与 Worker。
最小可跑配置(默认即此,无需修改):
HF_LLM_PROVIDER=fake # 改 deepseek / sensenova 并填 Key 才会调模型
HF_VIDEO_PROVIDER=remotion # mpt = MoneyPrinterTurbo 兼容模式;mock = 测试图HF_LLM_PROVIDER=fake 会用主题套进通用口播稿;在页面填写自己的内容或口播稿即可完全跳过模型调用。所有键位、降级组合与引擎侧配置见 docs/runbook/operations.md。
填主题与内容(可选)→ 选画幅、成片时长、配音语速 → 生成视频 → 看进度、预览成片、审核通过或驳回。可上传图片 / 视频作为本条任务的素材(只使用选中的文件)。成片按主题命名,任务列表可直接看到主题与成片。
cd backend && . .venv/bin/activate # Windows 用 .venv/Scripts/activate
python -m app.workers.cli --subject "一杯手冲咖啡的冲泡过程"
python -m app.workers.cli --topics ../config/topics.example.json \
--report ../output/reports/batch-report.json主题清单支持 ["主题A", "主题B"] 或带 topic / script / voice_name 的对象;填 script 会跳过 LLM,--from-script 可复用已落盘脚本,--limit N 只跑前 N 条,有任务失败时退出码为 1。批量 CLI 只是「批量入队 + 汇总报告」的薄封装,复用同一张任务表与同一条流水线,不是第二套实现。
| Method | Path | 说明 |
|---|---|---|
| POST | /api/tasks |
创建任务,立即返回 id |
| GET | /api/tasks/{id} |
轮询状态、进度、阶段、错误与结果 |
| POST | /api/tasks/{id}/retry · /cancel · /approve · /reject |
重试 / 取消 / 审核通过 / 驳回删除 |
| GET | /api/videos · /api/videos/{id}/stream |
成片列表 / 预览 |
| POST | /api/materials |
上传素材 |
| GET | /api/health · /docs |
健康检查 / OpenAPI 文档 |
任务状态机:PENDING → SCRIPTING → GENERATING → QC → WAITING_REVIEW → APPROVED,异常态 FAILED / CANCELLED。完整契约以 docs/design/hot-factory-overview-design.md 为准。
HotFactory 只负责业务流程与数据管理,外部能力统一收在 backend/app/providers/;新增能力前先确认上游是否已提供,不重复造第二套任务进度体系或字幕 / TTS 实现。
| 环节 | 由谁提供 |
|---|---|
| 结构化脚本与分镜 | providers/llm(fake / deepseek / sensenova),脚本落盘可手改 |
| 动态画面 | video-renderer/(Remotion + React + SVG),由 Storyboard JSON 驱动 |
| 旁白配音 | Edge TTS CLI(默认 .mpt-venv,可用 HF_MPT_TTS_COMMAND 指定)/ MPT 兼容模式 |
| 字幕、素材、整片合成 | MoneyPrinterTurbo(HF_VIDEO_PROVIDER=mpt) |
| 音轨封装与质检 | FFmpeg / ffprobe(本项目 providers/qc.py) |
| 任务持久化、进度、预览、审核 | 本项目:SQLite + 独立 Worker + FastAPI + Vue |
backend/app/ api / core / models / schemas / services / providers / storyboard / workers
backend/tests/ pytest
frontend/ Vue 3 + TypeScript + Vite + Element Plus
video-renderer/ Remotion 渲染工程
config/ 配置样例(config/.env 不入库)
data/ SQLite 与上传素材 —— 唯一需要备份的目录
output/ 成片、分镜、批量报告
logs/ 运行日志
docs/ design / runbook / progress
README 只保留「上手所需」,更长的说明都在这里:
| 想找什么 | 去哪 |
|---|---|
| 架构、接口契约、任务状态、能力边界(唯一真源) | docs/design/hot-factory-overview-design.md |
| 运行模式、出片命令、MPT 引擎与素材配置、降级组合 | docs/runbook/operations.md |
| GHCR 镜像、首次部署、升级、回滚、排错 | docs/runbook/docker-deploy-upgrade.md |
| 进度、验证记录与待办 | docs/progress/PROCESS.md |
| 第三方组件版本与许可证 | THIRD-PARTY-NOTICES.md |
| AI 协作规范(规范本体在全局目录,不随仓库分发) | AGENTS.md |
按三阶段推进,不提前实现后续阶段:
- 第一阶段(当前,alpha):跑通视频生产 —— 主题输入、AI 脚本与分镜、视频生成、质检、预览与人工审核。发布只保留接口与数据结构占位。
- 第二阶段:多模板、多音色、字幕增强、封面、自动质量评分、每日热点推荐。
- 第三阶段:抖音 / 快手 / 小红书 / 视频号 / B 站发布,官方 API 优先并保留人工确认。
已知限制:
- 无用户认证;Web 端口默认公网监听,必须靠安全组或反代收口。
- 热点靠手工主题 /
topics.json输入,没有官方热点 API,也没有自动选题评分。 - 质检只覆盖元数据(音视频流、时长、分辨率、大小);黑屏 / 静音语义检测与自动评分未实现。
- 容器启动与容器内 Chrome 渲染链路尚未在本机实跑(本机未装 Docker);镜像构建与 GHCR 推送已通过 CI 验证。镜像仅
linux/amd64。 - 前端全量引入 Element Plus,构建产物约 1 MB;Windows Docker Desktop 下用 bind mount 跑 SQLite(WAL)有已知风险,仅建议本地试跑。
- MoneyPrinterTurbo 是独立外部程序,Compose 只编排 Web + Worker,经
HF_MPT_API_BASE接入;上游没有官方镜像,不编造镜像名。
# 先激活 backend/.venv
cd backend && python -m pytest # 当前 110 个用例
cd frontend && npm run typecheck && npm run build # vue-tsc + vite build开发约定:先冻结架构与接口,再按模块实现,每完成一个模块跑测试;接口与任务状态字段变更先改架构文档再改代码。
欢迎提 Issue 或 PR。开始之前请先读 AGENTS.md 与架构文档:外部能力走 providers/ 适配层、复用优先、不引入 Redis / 消息队列等中间件、不建第二套进度体系。提交信息用中文并带 conventional 前缀(如 feat: / fix:),只提交本次改动涉及的具体文件。
本项目代码以 MIT License 发布。第三方组件的版本、许可证与来源记录在 THIRD-PARTY-NOTICES.md,接入或升级依赖前请复核上游 LICENSE 与服务条款。
能力上站在这些项目的肩膀上:MoneyPrinterTurbo、Remotion、FastAPI、Vue 3、FFmpeg、edge-tts 与 DeepSeek。