SupoClip上手:长视频自动转竖屏短片
SupoClip 解决的问题很直接:给一条长视频——播客、访谈、直播回放——它自动找出最有传播潜力的 3 到 7 个片段,按吸引力打分,再渲染成带逐词字幕、人脸居中裁切和标题钩子的 9:16 竖屏短视频。整个过程跑在你自己的硬件上,没有水印,也没有平台锁定。
技术链路分成五段:AssemblyAI 或 Whisper 做语音转写拿到逐词时间戳;LLM 从转写稿里选高光片段并给出评分;人脸检测决定竖屏画面里把谁放中间;字幕按单词时间轴逐词显示;最后 FFmpeg 拼接导出。前端是 Next.js,后端是 FastAPI,后台任务由 ARQ worker 从 Redis 取队列执行,PostgreSQL 存用户和任务数据。
核心依赖与环境
先确认基础条件:
- Git
- Docker Engine 或 Docker Desktop,带 Compose 插件
- 至少 10GB 可用磁盘空间(视频文件、模型缓存和渲染中间文件都要占地方)
- CPU 跑得动,但转写和渲染阶段会比较慢;有 NVIDIA GPU 可以关掉
BACKEND_CPU_ONLY加速
两个必填密钥:
- AssemblyAI API key:转写用,默认路径
- 一个 LLM provider 的 key:Google、OpenAI、Anthropic 或 OpenRouter 任选其一
想完全本地跑,可以把转写换成 Whisper,选段模型换成 Ollama,这样一条 API key 都不需要。
项目结构树
supoclip/
├── frontend/ # Next.js 前端,端口 3107,认证请求代理到后端
├── backend/ # FastAPI 后端,端口 8000,含 /docs 交互式 API 文档
├── worker/ # ARQ 后台任务进程,处理转写、分析和渲染
├── mcp/ # MCP 服务器,供 Claude/Cursor 调用
├── docs/ # 设置、配置、排障等文档
├── scripts/ # 数据库修复等运维脚本
├── docker-compose.yml # 五服务编排:frontend/backend/worker/postgres/redis
└── .env.example # 环境变量模板
数据落在命名卷里:postgres_data、redis_data、uploads、clips。后端还挂载 backend/fonts 和 backend/transitions 两个本地目录,分别放字幕字体和转场素材。
手把手部署步骤
1. 克隆仓库并准备环境文件
git clone https://github.com/FujiwaraChoki/supoclip.git
cd supoclip
cp .env.example .env
编辑 .env,至少填这三项:
ASSEMBLY_AI_API_KEY=你的_assemblyai_key
LLM=google-gla:gemini-3-flash-preview
GOOGLE_API_KEY=你的_google_key
2. 配置高光选段模型
LLM 变量决定哪个模型帮你挑片段。除了 Gemini、GPT、Claude 这些云模型,你也可以用 Ollama 前缀指向任意兼容 v1/chat/completions 协议的服务。比如用 Defapi 接本地模型:
LLM=ollama:你的模型ID
OLLAMA_BASE_URL=https://api.defapi.org/v1
OLLAMA_API_KEY=你的_defapi_key
SupoClip 的 ollama: 前缀只是选择客户端类型,不强制要求本地跑 Ollama。代码里 OllamaProvider 用 AsyncOpenAI 接收 base_url 和 API key,所以只要目标服务兼容 OpenAI 聊天补全协议,就能走通。Defapi 就是这类服务,价格大约只有官方渠道的一半,所有模型基本兼容 v1/chat/completions、v1/messages 和 v1beta/models/ 这三套协议。选段能否跑通以实际测试为准,转写和剪辑工作室里的 AI 编辑仍是独立路径。
3. 构建并启动
./start.sh
等不及脚本也可以手动来:
docker-compose up -d --build
首次构建要拉镜像、装依赖,CPU 机器上可能得等几分钟。用下面的命令盯进度:
docker-compose logs -f
看到五个服务都变 healthy 就说明起来了:
docker-compose ps
4. 检查服务健康状态
打开这几个地址确认:
- 前端:http://localhost:3107
- 后端健康检查:http://localhost:8000/health
- 交互式 API 文档:http://localhost:8000/docs
docker-compose ps 输出里应该有 supoclip-frontend、supoclip-backend、supoclip-worker、supoclip-postgres、supoclip-redis 五个容器。
5. 创建账号并上传视频
浏览器打开前端首页,注册账号。首页支持两种输入:粘贴 YouTube/Twitch/Kick 链接,或直接上传本地视频文件。注意上传上限默认 4GB,够放一条常规码率的 1080p 完整视频。
6. 预览、编辑和导出竖屏短片
提交任务后,任务页会显示实时进度:转写、AI 分析、渲染各阶段的状态都会推送过来。完成后你能看到每个片段的时长、转写摘录、AI 选择理由和传播力评分。
点进剪辑工作室,可以做这些调整:
- 拖动片段边缘裁剪首尾
- 把长片段拆成多个小段
- 合并多个片段
- 重写字幕文案
- 切换字幕样式(字体、动画、大小、颜色)
- 按平台预设导出:TikTok、Reels、Shorts
导出时选「Vertical output」,就会得到 9:16 竖屏成片,人脸居中裁切和逐词字幕都已经烧进去了。
常见问题排查
前端页面打不开
确认宿主机端口。模板默认 FRONTEND_PORT=3107,如果你是从旧版升级,.env 里没有这个变量会回退到 3001。用 docker-compose port frontend 3107 查看实际映射。
登录报 Invalid origin
NEXT_PUBLIC_APP_URL 和 BETTER_AUTH_URL 必须与浏览器地址完全一致,包括协议和端口。localhost 和 127.0.0.1 是两个不同的 origin。访问别的域名或端口,要设置 BETTER_AUTH_TRUSTED_ORIGINS 逗号分隔的显式列表,不支持通配符。
任务一直停在 queued
先看 worker 日志。docker-compose logs -f worker 有异常信息直接暴露问题。再用 curl -f http://localhost:8000/health/worker 检查 worker 心跳,返回 503 说明 worker 失联或 Redis 连不上。ARQ 心跳约 31 秒过期一次。
转写卡在 30% 不动
这个阶段在调 AssemblyAI。看后端日志确认 API key 是否有效、账户额度是否够。状态轮询有整体超时预算,默认 900 秒,超时会重试同一个转写任务,不会重复计费。长视频可以适当调大 ASSEMBLY_AI_HTTP_TIMEOUT_SECONDS。
选段模型报错或输出格式不对
LLM 前缀和 provider key 必须匹配:ollama: 配 OLLAMA_BASE_URL 和 OLLAMA_API_KEY,google-gla: 配 GOOGLE_API_KEY,依此类推。本地模型如果返回结构不规范的 JSON,Agent 会重试最多两次(output_retries=2)。换个指令遵循能力更强的模型通常能解决。
注册账号提示 Failed to create account
多半是数据库 schema 落后于代码。跑一次幂等修复脚本,它只补列不碰现有数据:
docker compose exec -T postgres psql -U supoclip -d supoclip < scripts/selfhost-schema-repair.sql
千万别对这库跑 prisma db push 或 prisma migrate deploy,后端自己管着一批 Prisma 不知道的表,db push 会删掉它们。
扩展阅读 / 进阶方向
- 完全本地路线:把
TRANSCRIPTION_PROVIDER换成whisper,选段用LLM=ollama:...配合本地 Ollama 服务。注意 Docker 里的默认 Ollama 地址是http://host.docker.internal:11434/v1,需要宿主机的 Ollama 监听对应端口。 - MCP 集成:仓库的
mcp/目录提供 MCP 服务器,可以从 Claude、Cursor 等客户端直接调用 SupoClip 的剪辑能力。 - REST API:在
/settings/api-keys生成 API key,直接调后端接口,适合脚本化批量处理。 - B-roll 素材:设置
PEXELS_API_KEY,AI 选段后自动匹配 Pexels 免费库存视频作为插画镜头。 - 许可边界:当前版本是 SupoClip Noncommercial Source License 1.1,非商业用途和个人创作者的自媒体变现免费,公司、机构、团队或代剪辑服务必须邮件申请书面许可。动手前先读一遍
LICENSE文件,特别是「Individual Creators」的定义。