Video Wizard 是一个开源工具包，面向 AI 驱动的视频内容工作流，主要能力包括识别爆款片段、生成风格化字幕、渲染适合社交平台的竖屏视频。它支持自托管、本地优先，无 SaaS 锁定。截至 2026 年 5 月，字幕生成器是完成度最高的流程；渲染任务运行在真实 PostgreSQL 支持的任务队列上，具备重试和退避机制，因此 UI 在 worker 处理长任务时保持响应。认证采用邮箱加 bcrypt 密码，存储于本地数据库。
内置字幕模板：viral、minimal、modern、default、highlight、colorshift、hormozi、mrbeast、mrbeastemoji。输出格式：竖屏 9:16（TikTok / Reels / Shorts）、方形 1:1、竖屏 4:5、横屏 16:9。品牌套件覆盖（logo、颜色、字体）适用于每一个模板。
快速开始（一条命令）：需要 Docker Desktop（或任何 compose-v2 运行时）。然后打开 http://localhost:3000/signup 创建账户，并通过字幕生成器跑一个视频。/jobs 页面会随着 worker 处理队列实时显示渲染进度。对于手动/混合设置（宿主机运行 Node，Python 和 Postgres 在 Docker 中，迭代更快），请参阅 CONTRIBUTING.md。
三个值得了解的技术亮点：
- 尖叫架构（Screaming architecture）——文件结构直接说明应用功能。features/video/ 表示“我处理视频”；server/services/ 负责业务逻辑；API 路由仅处理 HTTP。
- 真实任务队列——长渲染通过 task_queues / queue_tasks 这两张 Postgres 表进行。worker（pnpm worker）通过 SELECT ... FOR UPDATE SKIP LOCKED 原子地领取任务，以指数退避重试，并将 Remotion 的逐帧进度转发给面向用户的 job 行，让 /jobs 保持实时更新。
- Auth.js v5 + Drizzle——邮箱加 bcrypt 密码存储在 PostgreSQL 中。Auth.js 的 OAuth 表已在 schema 中，便于后续添加 Google / GitHub 等登录方式。
完整细节：AGENTS.md（架构与约定）、docs/ARCHITECTURE.md（系统概览）。
技术栈：
- 前端：Next.js 16（App Router、Turbopack）、TypeScript 严格模式、Tailwind v4、shadcn 风格组件、Vercel AI SDK + GPT-4o、Auth.js v5（Credentials provider）。
- 数据库：PostgreSQL 17 + Drizzle ORM（pnpm db:generate / db:migrate / db:studio）。
- 队列/worker：基于 Postgres（无 Redis），由独立的 tsx 脚本（pnpm --filter web worker）消费。
- 后端：Python 3.11 + FastAPI、OpenAI Whisper、MediaPipe、FFmpeg。
- 渲染：Remotion 4、Express 任务队列。
- 工具链：pnpm + Turborepo、Husky + lint-staged + commitlint（Conventional Commits）。
贡献：请参阅 CONTRIBUTING.md。要点：
- cp .env.docker.example .env.docker（设置 AUTH_SECRET + OPENAI_API_KEY）。
- docker compose up。
- 从 good first issue 标签或 CONTRIBUTING.md 中建议的高杠杆领域挑选任务。
- 使用 Conventional Commits，提交聚焦的 PR，UI 变更附上截图。
基本规则见 AGENTS.md：禁止 any、业务逻辑保持在 services 中、长任务走队列。
文档地图：
- AGENTS.md——完整架构、API 参考、所有约定
- CONTRIBUTING.md——设置、PR 流程、从哪里开始
- docs/ARCHITECTURE.md——系统概览
- docs/COMMIT_CONVENTIONS.md——Conventional Commits
- docs/DOCKER_SETUP.md——Docker 设置说明
- docs/HUSKY_SETUP.md——Git 钩子
- docs/SUBTITLE_TIMING_ADJUSTMENT.md——字幕同步调优
MIT © Video Wizard Contributors。
