Overview
Director is an open-source framework from VideoDB for building video agents that handle tasks such as search, editing, compilation and generation from a chat prompt and stream the result back. Its maintainers describe it as "ChatGPT for videos": a request like "upload this video and send the highlights to my Slack" is broken into steps and handed to the agents that can do each one.
At its core is a reasoning engine that keeps the conversation's context, decides which agents to call, runs them and folds their responses into one answer, pushing progress updates to the interface as it goes. The repository ships a pool of ready-made agents — among them upload, indexing, search, summarisation, prompt-based clipping, subtitles, transcription, dubbing, voice cloning and replacement, profanity censoring, audio, image and video generation, text-to-movie, web search, Slack and Composio integrations — and a sample agent to copy when writing your own.
The stack is a Python (Flask and Socket.IO) backend with a Vue chat front end that includes a video player and a collection view. Video storage, indexing and streaming run on VideoDB's hosted "video-as-data" service, so a VideoDB API key is required; LLM calls go to OpenAI, Anthropic or Google, and optional agents use their own providers such as ElevenLabs, Replicate, Stability AI, Kling or fal. Sessions persist to SQLite or PostgreSQL. VideoDB also runs a hosted version of the same chat app.
What it does
- Reasoning engine that plans a request, orchestrates several agents and streams live progress to the chat
- 20+ pre-built agents for search, summaries, clips, subtitles, translation, dubbing, voice cloning and generation
- Chat UI with built-in video playback and a collection view for browsing a media library
- Pluggable LLMs and GenAI providers configured through the backend `.env` file
- New agents added by copying the sample agent, implementing `run()` and registering it in the chat handler
- Runs locally on macOS, Linux or WSL, or deploys from templates for Render and Railway
Getting started
Director needs Python 3.9+, Node.js 22.8.0+ and npm, plus a VideoDB API key and at least one LLM provider key.
Clone the repository
git clone https://github.com/video-db/Director.git
cd DirectorRun the setup script
`setup.sh` installs Node.js 22.8.0 through nvm, installs Python and pip, and creates virtual environments for the front end and back end.
./setup.shAdd your keys
Edit the generated `.env` files. The backend sample lists `VIDEO_DB_API_KEY`, the LLM keys (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLEAI_API_KEY`), the database type, and optional keys for agents such as Slack, ElevenLabs, Replicate or Kling.
Start the app
`make run` starts both servers: the backend on http://127.0.0.1:8000 and the chat front end on http://127.0.0.1:8080. Use `make run-be` or `make run-fe` to start just one.
make runWrite your own agent
Copy the sample agent in `backend/director/agents/`, rename the class and set `agent_name` and `description`, implement `run()` using the content types (text, video, image, search result) and `push_update()` for progress, then import it in `backend/director/handler.py` and add it to the `self.agents` list in `ChatHandler`.
Commands and code are distilled from the project's own documentation — always check the official repo for the latest.
When to use it
- Turn long recordings into highlight clips or summaries from a chat request
- Search a video library for specific spoken or visual moments and clip them
- Dub, subtitle or translate existing videos, or generate a video from a script
- Build a custom video workflow agent on top of VideoDB's storage, indexing and streaming
How Director compares
Director alongside other open-source video generation tools AI/TLDR tracks, ranked by GitHub stars.
| Tool | Stars | What it does |
|---|---|---|
| MoneyPrinterTurbo | ★ 135k | A self-hosted WebUI, API and CLI that turns one topic or keyword into a finished short video — script, stock or generated footage, voiceover, subtitles and music. |
| OpenMontage | ★ 71.3k | An agentic video production system that gives a coding assistant 12 pipelines and 100+ tools to research, script, generate and render a video end to end. |
| HyperFrames | ★ 71k | HeyGen's HTML-to-video renderer: author a composition in HTML, CSS and JS, preview it in a browser, then render the same input to a deterministic MP4 locally or on AWS Lambda. |
| Open Generative AI | ★ 31.4k | MIT-licensed desktop and web studio for AI image, video and lip-sync generation that runs hosted models through the Muapi.ai API, with optional local image models in the desktop app. |
| Hypit | ★ 25.2k | A markup language and compiler that lets a coding agent rebuild a reference video as an editable workflow — footage, captions, B-roll and effects anchored to words rather than timestamps — and render variants in one command. |
| Toonflow | ★ 19.2k | Infinite-canvas workbench for AI short-drama production, taking a novel through chapter events, script, storyboards and video nodes. |
| waoowaoo | ★ 14.7k | Self-hosted creative workspace for AI image and video: a canvas holding references and generated assets, a side Assistant that develops the brief, and model-aware controls over your own OpenRouter key. |
| Director | ★ 1.6k | A chat-driven framework of video agents built on VideoDB |