Video Wizard is an open-source toolkit for AI-driven video content workflows, with core capabilities including identifying viral clips, generating stylized subtitles, and rendering vertical videos suited for social platforms. It supports self-hosting, is local-first, and has no SaaS lock-in. As of May 2026, the subtitle generator is the most complete workflow; rendering tasks run on a real PostgreSQL-backed task queue with retry and backoff mechanisms, so the UI stays responsive while workers process long tasks. Authentication uses email plus bcrypt passwords, stored in the local database.
Built-in subtitle templates: viral, minimal, modern, default, highlight, colorshift, hormozi, mrbeast, mrbeastemoji. Output formats: vertical 9:16 (TikTok / Reels / Shorts), square 1:1, vertical 4:5, landscape 16:9. Brand kit coverage (logo, colors, fonts) applies to every template.
Quick start (one command): requires Docker Desktop (or any compose-v2 runtime). Then open http://localhost:3000/signup to create an account and run a video through the subtitle generator. The /jobs page shows rendering progress in real time as workers process the queue. For manual/hybrid setups (Node running on the host, Python and Postgres in Docker, faster iteration), see CONTRIBUTING.md.
Three technical highlights worth knowing:
- Screaming architecture — the file structure directly states what the app does. features/video/ means "I handle video"; server/services/ handles business logic; API routes handle only HTTP.
- Real task queue — long renders go through the two Postgres tables task_queues / queue_tasks. The worker (pnpm worker) atomically claims tasks via SELECT ... FOR UPDATE SKIP LOCKED, retries with exponential backoff, and forwards Remotion's frame-by-frame progress to the user-facing job row, keeping /jobs updated in real time.
- Auth.js v5 + Drizzle — email plus bcrypt passwords stored in PostgreSQL. Auth.js's OAuth tables are already in the schema, making it easy to add Google / GitHub and other sign-in methods later.
Full details: AGENTS.md (architecture and conventions), docs/ARCHITECTURE.md (system overview).
Tech stack:
- Frontend: Next.js 16 (App Router, Turbopack), TypeScript strict mode, Tailwind v4, shadcn-style components, Vercel AI SDK + GPT-4o, Auth.js v5 (Credentials provider).
- Database: PostgreSQL 17 + Drizzle ORM (pnpm db:generate / db:migrate / db:studio).
- Queue/worker: Postgres-based (no Redis), consumed by a standalone tsx script (pnpm --filter web worker).
- Backend: Python 3.11 + FastAPI, OpenAI Whisper, MediaPipe, FFmpeg.
- Rendering: Remotion 4, Express task queue.
- Toolchain: pnpm + Turborepo, Husky + lint-staged + commitlint (Conventional Commits).
Contributing: see CONTRIBUTING.md. Key points:
- cp .env.docker.example .env.docker (set AUTH_SECRET + OPENAI_API_KEY).
- docker compose up.
- Pick a task from the good first issue label or the high-leverage areas suggested in CONTRIBUTING.md.
- Use Conventional Commits, submit focused PRs, and attach screenshots for UI changes.
Basic rules are in AGENTS.md: no any, keep business logic in services, long tasks go through the queue.
Documentation map:
- AGENTS.md — full architecture, API reference, all conventions
- CONTRIBUTING.md — setup, PR process, where to start
- docs/ARCHITECTURE.md — system overview
- docs/COMMIT_CONVENTIONS.md — Conventional Commits
- docs/DOCKER_SETUP.md — Docker setup instructions
- docs/HUSKY_SETUP.md — Git hooks
- docs/SUBTITLE_TIMING_ADJUSTMENT.md — subtitle sync tuning
MIT © Video Wizard Contributors.
