Avatar Studio — Short-Form Engine

Clone yourself from photos, then turn your voice into a retention-optimized short video of your avatar — optionally emulating the style of any reel. Built to the v9 spec: resilient by construction (nothing breaks), mobile-first, serverless.

Run it

npm install
cp .env.example .env.local   # fill in keys (see below) — optional for the demo
npm run dev                  # http://localhost:3000

The whole wizard is walkable without any keys (demo mode). The AI Director is pure and runs for real — you'll see genuine scene plans, hooks and prompts. Live video generation switches on once you add the keys.

Keys (what unlocks what)

Key	Unlocks	Required?
FAL_KEY	Video (Seedance), avatars (Nano Banana), transcript (Whisper), upscale (Topaz)	Yes for real output
GEMINI_API_KEY	Reel analysis → style emulation	Optional (degrades to no-emulation)
SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY	Media storage + job state	Yes to persist
APIFY_TOKEN or SCRAPECREATORS_API_KEY	Auto-fetch IG/TikTok reels	Optional (falls back to file upload)

Missing keys never crash the app — GET /api/preflight reports exactly what's available and the UI shows friendly fallbacks.

Verify

npm run verify   # typecheck + 74 unit tests + lint
npm run build    # production build

Architecture (where things live)

src/lib/resilience/   timeout · backoff · retry · circuit breaker · content-hash cache · semaphore · fallback chain
src/lib/schemas/      every JSON contract (§3/§6) as zod — types + runtime validation
src/lib/reel/         platform detect + resilient acquisition chain + upload floor
src/lib/providers/    fal (Seedance/Nano Banana/Whisper/Topaz) + Gemini analyzer — all wrapped in the resilience layer
src/lib/director/     AI Director (§7) + scene→Seedance prompt builder (§8)
src/lib/state/        job state machine (§14)
src/components/        mobile-first wizard + editable scene-timeline cards
src/app/api/          preflight · director/preview (key-free real plan)

Live-verified (real keys, real endpoints)

• Gemini reel analysis — a real video → schema-valid style_blueprint (end-to-end through /api/analyze-reel).
• Supabase — storage upload + public read + DB round-trip via REST; RLS hardened (security advisor: 0 warnings).
• SSRF guard — 169.254.169.254 and other internal targets rejected with 400 before any fetch.
• fal (Seedance/Nano Banana/Whisper/Topaz) — code correct and reaches fal, but the account balance is exhausted; top up at fal.ai/dashboard/billing and the render path runs. Logic is proven via mocked tests.

What's proven vs. key-gated

• Proven by 112 tests + a running server + a real ffmpeg run: resilience core (+composition), schemas, reel detection/chaining, the Director, the scene builder, the §9.1 reference_images XOR first/last_frame invariant, QC gates, the state machine, the orchestrator (happy / partial / reel-skip / fetch-fail / analysis-skip paths), webhook+poll dual completion, the ffmpeg assemble→export pipeline (generates, concats and exports real clips), and the Supabase cache/storage adapter (against an in-memory fake client).
• Provider HTTP layer exercised against mocked responses: Seedance render+re-roll+dead-letter, Gemini analyze (parse, schema-reminder retry, graceful degradation), Whisper, Nano Banana, Topaz identity gate + ByteDance fallback + 480p degrade, reel acquisition chain + upload floor. The only thing real keys change is the credentials — the call/parse/retry/fallback logic is proven.
• Needs your keys to run live end-to-end: the actual paid model calls + real Supabase project.

Wired but not yet load-tested live

Vercel Workflows is modeled by the in-process orchestrator + dualComplete; for production, deploy the orchestrator as a Vercel Workflow so durability survives restarts. Caption ASS generation from Whisper word timestamps is the one remaining authoring step (burn-in args exist).