第 2 课
提交首个剪辑任务并导出 9:16 字幕片
注册后提交竖屏剪辑任务，跟到 completed，并下载 9:16 字幕片。
学习位置仅保存在当前浏览器，有效期 180 天。
图文讲义
提交首个剪辑任务并导出 9:16 字幕片
本课按官方 docs/setup.md「First-Run Checklist」、docs/app-guide.md 核心工作流，以及 docs/troubleshooting.md 整理。
前置：第 1 课已能打开 **http://localhost:3107**，且.env里 AssemblyAI（或 Whisper）与 LLM 已成对配置。
路径说明：本课继续走 自托管 UI（与第 1 课同一实例）。若你只想体验成片、暂不运维，也可打开托管站 https://www.supoclip.com/ 用同一套「粘贴 YouTube / 上传 → 等进度 → 下载」流程；下面步骤以自托管为准，按钮与状态名以 app-guide 为准。
你将得到什么
- 一个已注册并登录的本机账号
- 至少一个任务走完
queued→processing→completed - 可预览、可下载的竖屏（
vertical）字幕短片 - 缺 Key / worker 挂掉时的对照排错动作
一、注册并登录
- 浏览器打开 http://localhost:3107
- 进入
/sign-up用邮箱与密码注册（Better Auth + PostgreSQL / Prisma，见 app-guide） - 若已关闭注册（
DISABLE_SIGN_UP=true），改用已有账号走/sign-in
对照结果：
- 能进入首页
/（任务创建屏），而不是反复卡在登录页。 - 若提示 Invalid Origin：回到第 1 课，把
NEXT_PUBLIC_APP_URL、BETTER_AUTH_URL改成与地址栏完全一致的 origin（含http与端口），重启 frontend。
二、创建第一个任务（官方 Create a task）
首页 / 就是主创建屏（app-guide「Home」）。按下列顺序操作：
- 选来源
- YouTube：粘贴公开链接，支持例如
https://www.youtube.com/watch?v=...https://youtu.be/...- 以及文档提到的 embed 风格链接
- Upload：上传本机视频文件（经前端上传 API，后端落临时区再处理）
- YouTube：粘贴公开链接，支持例如
- 建议先用短素材（自托管教程 Verify）：短视频能更快暴露密钥/网络问题。
- 输出与字幕（创建前可改默认）
- Output format：选
vertical（9:16，面向 Shorts / Reels / TikTok） - 打开字幕（Subtitle toggle）
- 可选：字体 / 字号 / 颜色、Caption template、是否 Include B-roll（需已配
PEXELS_API_KEY，否则前端会显示 B-roll 不可用）
- Output format：选
- 提交任务。
对照结果：
- 提交后进入任务详情
/tasks/[id]（或列表/list里能看到新任务）。 - 状态先出现
queued，随后变为processing。 - 任务页应出现实时进度（后端 SSE：
GET /tasks/{id}/progress）。
自托管且
SELF_HOST=true时：官方说明计费摩擦最小、不按套餐卡生成次数。若你改成了SELF_HOST=false却没配 Stripe，可能无法正常建任务——初学请保持自托管默认。
三、盯进度到完成
在任务详情页等待状态变为 completed。管道大致顺序（结合 architecture / troubleshooting 描述）：
- 拉取 YouTube 或读取上传文件
- 转写（默认 AssemblyAI 词级时间戳；也可 Whisper / youtube_captions）
- LLM 选段 + 病毒性打分（hook / engagement / value / shareability）
- 渲染：人脸居中竖裁、字幕烧录、钩子标题等
可另开终端观察 worker：
cd supoclip
docker compose logs -f worker
健康抽检（自托管教程 / troubleshooting）：
docker compose ps
curl -f http://localhost:8000/health
curl -f http://localhost:8000/health/worker
curl -f http://localhost:8000/health/db
对照结果（成功）：
- UI 状态：
queued→processing→completed（不会永久停在 queued）。 - 完成后同一任务页出现片段列表：时长、转写摘录、AI 理由、病毒性分数、预览与下载。
- 点开预览：画面为竖屏、说话人大致居中，字幕与口型大致对齐（词级字幕依赖转写质量）。
对照结果（故意缺 Key 时你会看到什么）：
| 缺失 | 典型表现（troubleshooting） |
|---|---|
无 / 错 ASSEMBLY_AI_API_KEY（且仍用 AssemblyAI） | 任务进入 processing 后失败；worker/backend 日志出现转写/AssemblyAI 错误；状态常变为 error。进度卡在约 30% 时优先查转写日志。 |
LLM=openai:... 却无 OPENAI_API_KEY（或 Google/Anthropic 前缀与 Key 不配） | 转写后分析失败；约 50% 附近卡住或转 error；日志提示 provider / API key。 |
| worker 未运行 / Redis 异常 | 任务一直 queued；curl -f http://localhost:8000/health/worker 可能 503。 |
| YouTube 拉取失败 | 任务很早 error；日志与网络/反爬/可选 APIFY_API_TOKEN 相关——可改用本地上传绕过下载。 |
改完 .env 后必须重建/重启相关服务，例如：
docker compose down
docker compose up -d --build
四、预览、轻编辑与导出
任务完成后（app-guide「Review / Edit clips」）：
- 在片段卡片上 预览 与 下载。
- 需要微调时打开 Clip Studio：
/tasks/[id]/edit（裁剪、分割、合并、改字幕、导出平台预设如 TikTok 等——以当前 UI 按钮为准）。 - 设置页
/settings可保存默认字体/字号/颜色，方便下次创建。
对照结果：
- 本机能播放下载下来的竖屏成片。
- 列表页
/list能看到该任务为 completed；需要时可 Cancel / Resume / Delete（以界面提供的操作为准）。
五、排错速查（首个任务专用）
先跑这组命令（troubleshooting「Start Here」）：
docker compose ps
docker compose logs -f
docker compose logs -f backend
docker compose logs -f worker
| 症状 | 动作 |
|---|---|
| 一直 queued | 确认 worker 容器在跑；curl -f http://localhost:8000/health/worker；看 Redis |
| processing 后 error | 核对 .env 中 AssemblyAI 与 LLM+对应 Key；看 worker 异常栈 |
| 前端能开但提交失败 | 查 NEXT_PUBLIC_API_URL、浏览器 Network、backend 日志 |
| B-roll 选项灰掉 | 未设 PEXELS_API_KEY 属正常；不影响基础竖屏字幕片 |
| 想清空重来（会删数据） | 仅实验环境：docker compose down -v 再 up -d --build |
向官方提 Issue 前建议准备（troubleshooting）：你执行的命令、打码后的相关 .env 项、浏览器报错、backend/worker 日志片段、YouTube 还是上传、以及 SELF_HOST 取值。
六、可选：托管站对照（非本课主路径）
若本机资源紧张，可先在 https://www.supoclip.com/ 用托管流水线熟悉「粘贴链接 → 等成片」的产品体验，再回到自托管做无水印、可改源码的完整控制。演示成片也可参考：https://www.supoclip.com/demo
本课考核仍以第 1 课起的 Docker 实例为准。
本课小结
| 步骤 | 动作 | 成功信号 |
|---|---|---|
| 注册 | /sign-up → / | 进入创建屏 |
| 提交 | YouTube 或上传 + vertical + 字幕 | 进入 /tasks/[id]，出现进度 |
| 等待 | 看 UI + logs -f worker | completed + 可预览 |
| 导出 | 下载 / 可选 Clip Studio | 本机有 9:16 成片 |
| 排错 | 缺 Key → error；无 worker → 久 queued | 能对照上表定位 |
两课合计：Docker 自托管起栈 + 跑通首条剪辑流水线。配置全集见 docs/configuration.md；API / MCP 见仓库 docs 与 README「Ways to Use」。
来源
- https://github.com/FujiwaraChoki/supoclip/blob/main/docs/setup.md
- https://github.com/FujiwaraChoki/supoclip/blob/main/docs/app-guide.md
- https://github.com/FujiwaraChoki/supoclip/blob/main/docs/troubleshooting.md
- https://www.supoclip.com/blog/self-host-supoclip-docker
- https://www.supoclip.com/
- https://github.com/FujiwaraChoki/supoclip
