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. 检查服务健康状态

打开这几个地址确认:

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」的定义。