How travisbuilds/duckduckgoose works
HFVG turns an episode brief into an approved, budget-controlled short video through a FastAPI/Next.js front end and durable Temporal workflows. The main path parses and plans a story, pauses for human approvals, generates and checks stills and clips, edits and adds audio, then gates final delivery. Separate branches cover cast assets, provider integrations, budget and model-limit safeguards, and retries/reconciliation. The README documents the end-to-end stages; some subsystem links rely on the source index because their implementation excerpts were not supplied.
Main entry points: episode_v2.py Episode workflow · studio_generation.py Still and clip generation · main.py Studio API · worker.py Worker
Components 22
User interfaces
- Studio UI
web/app/studio/episodes/[id]/page.tsx - Studio API
api/main.py - Cast routes
api/cast_routes.py
Workflow orchestration
- Temporal
- Worker
hfvg/worker.py - Episode workflow
hfvg/workflows/episode_v2.py - Shot workflow
hfvg/workflows/shot.py
Story and generation
- Story planning
hfvg/activities/story_shaping.py - Shot plans
hfvg/shot_data.py - Cast assets
hfvg/cast_plan.py - Still and clip generation
hfvg/activities/studio_generation.py - AI providers
hfvg/providers/__init__.py
Safety and budget
- Preflight limits
hfvg/preflight.py - Budget ledger
hfvg/budget.py - Quality gates
hfvg/activities/qc.py - Episode state
hfvg/studio_db.py
Media and delivery
- Edit and encode
hfvg/activities/media.py - Audio generation
hfvg/activities/audio.py - ElevenLabs
hfvg/providers/elevenlabs.py - Final video
hfvg/activities/media.py
Other components
- Creator
- Human approver
Connections 25
- Creator → Studio UI: manages episodes
README.md - Studio UI → Studio API: uses API
README.md - Studio API → Temporal: starts workflows
README.md - Studio API → Episode state: reads and writes
api/main.py - Studio API → Cast routes: mounts routes
api/main.py - Cast routes → Episode state: uses cast state
- Temporal → Worker: dispatches tasks
README.md - Worker → Episode workflow: registers workflow
hfvg/worker.py - Worker → Shot workflow: registers workflow
hfvg/worker.py - Episode workflow → Story planning: shapes story
- Episode workflow → Shot plans: plans shots
- Episode workflow → Cast assets: generates references
- Episode workflow → Still and clip generation: runs generation
hfvg/workflows/episode_v2.py - Shot workflow → Still and clip generation: runs shot jobs
hfvg/workflows/shot.py - Still and clip generation → AI providers: submits requests
hfvg/activities/studio_generation.py - Still and clip generation → Preflight limits: validates limits
hfvg/activities/studio_generation.py - Still and clip generation → Budget ledger: reserves spend
hfvg/activities/studio_generation.py - Episode workflow → Quality gates: runs quality gates
hfvg/workflows/episode_v2.py - Episode workflow → Episode state: tracks episode state
hfvg/workflows/episode_v2.py - Human approver → Episode workflow: approves gates
README.md - Episode workflow → Edit and encode: assembles edit
README.md - Episode workflow → Audio generation: generates audio
README.md - Audio generation → ElevenLabs: requests voiceover
hfvg/activities/audio.py - Episode workflow → Final video: delivers video
README.md - Edit and encode → Final video: renders video
hfvg/activities/media.py