Tubematic — Documentation
Tubematic turns a topic into a finished YouTube Short: it researches topics, writes a script, voices it, generates imagery, animates it in code, renders an mp4, has an AI watch the result for defects, and stops at three points where a human has to say yes.
Every scene is a React component an AI agent writes for that specific video, compiled and rendered by Remotion. The output is real code, which is why you can read exactly what produced any frame.
The documentation is split by who is reading. Pick the entry point that matches what you want to do.
| You want to… | Start at |
|---|---|
| Get it running and make a first video | Quickstart |
| Install, run, operate and upgrade it | User guide |
| Understand how it works, change it, or build on it | Developer docs |
| See what changed in a release | Release notes |
User guide
For anyone running Tubematic. No knowledge of the code is assumed.
| 1 · Overview | What it is, what it produces, the design decisions that shape everything else, and a glossary. Read this first |
| 2 · Installing | Prerequisites, what the dashboard exposes on the network, the install wizard, installing an agent, your first video, verifying and uninstalling |
| 3 · Using Tubematic | The day-to-day: the ways to make videos, scheduling, the control knobs, the checkpoints you approve, pausing and monitoring |
| 4 · The Dashboard | Signing in, every page and what it is for, and the actions you take there |
| 5 · Settings | Every setting: what it does, its default, and when to change it |
| 6 · Publishing | Connecting social accounts, publishing and scheduling posts, and Auto Pilot |
| 7 · Upgrading | Moving to a new version, versioning, backups, and rollback |
| 8 · Troubleshooting | Symptoms and where the cause usually is |
| 9 · Remote Access | Using the dashboard from another machine: Twingate, or HTTPS with Caddy or nginx |
Developer docs
For contributors and anyone integrating with or extending Tubematic.
| 1 · Architecture | Containers, processes, how they talk, where files live, the repository map, and the failure model |
| 2 · The Pipeline | The state machine in full — every status, every transition, the human checkpoints, and the revision loop |
| 3 · Database | Every table and column, the migration model, and how to add one |
| 4 · Settings internals | How settings and credentials are stored, masked and verified, and how to add a setting |
| 5 · HTTP API | Every Flask route — parameters, responses, status codes, and known quirks |
| 6 · MCP Server | Every agent tool, validate_job's checks, and the scene-work claim |
| 7 · The Agent Layer | Skills, slash commands, installing an agent and how videos are assigned to one |
| 8 · Scripting and Voice | Script segments, length budget, pronunciation and pause markup, timeline.json, script profiles |
| 9 · The Remotion Project | The frame model, compositions, dynamic scene dispatch, scene-config.json, the installed component library |
| 10 · Scene Authoring | How a scene gets written — the two visual registers, the PHOTO / HYBRID / DIAGRAM / STICK taxonomy, cadence, the revision path, adding a component |
| 11 · Rendering and Review | Rendering, timeouts and retries, Gemini video review, the text-layout audit |
| 12 · The Worker | The always-on loop that renders, settles posts, runs Auto Pilot and the timed sweeps — every pass, its order and how often it runs |
| 13 · The Poller | poll.py, the cron-started supervisor that runs agent sessions — the loop, the three lanes, one stage per session, timeouts and orphans |
| 14 · Publishing internals | The postforme client, schema, routes, the worker's publishing passes, and the design decisions behind them |
| 15 · Dashboard internals | The Next.js app — stack, the request guard, the proxy and stream routes, components, the action model |
| 16 · Infrastructure | Compose services, authentication, volumes, images, cron, and day-to-day operating commands |
| 17 · Development | Where verification belongs, release tooling, the CI workflow shape, conventions, and contributing |
| 18 · Releases | What a release consists of, release branches, image tags, and how migrations ship |
| Test suites | Every test suite — what each file guards, how to run it, and the traps each one encodes |
Reading routes
Just want to run it. Quickstart → Using Tubematic → The Dashboard, and Remote Access to use it from another machine.
Want to change how videos look. Overview → The Remotion Project → Scene Authoring. This is the main extension surface.
Want to change how the AI behaves. The Pipeline → The Agent Layer → MCP Server. Most behaviour lives in markdown skills, not code.
Integrating something external. Architecture → HTTP API → Database.
Something is broken. Troubleshooting.
Conventions in these docs
- Code is cited by symbol —
pipeline.py::patch_video— never by line number, so a citation cannot rot when a file is edited above it. - Diagrams are inline ```mermaid fences, rendered natively by GitHub. There is no build step.
- No test counts, suite totals, or dated claims. Run the suite.
- Each explanation lives on one page; others link to it. A user-guide page covers what you do and see, and links to the developer page that explains how it works.
- Where a design decision looks wrong or over-engineered, the reason is stated. Those notes are the most valuable part of this documentation and the easiest to accidentally undo.
These documents are public and must never carry stale information. Any change that adds or alters a tool, route, settings key, status, schema column, component or skill rule is not finished until the relevant page reflects it — and until the neighbouring claims it invalidated have been re-checked. See Development — Keeping the docs true.