TechDemoForge is a local-first engine for turning dense technical source material into highly accurate, structured demo videos. Built for developers, infrastructure teams, and technical founders, it replaces the manual overhead of crafting video explainers by programmatically converting engineering notes, architecture specs, and raw code into polished video assets.
By operating locally, TechDemoForge ensures that sensitive intellectual property and proprietary engineering concepts remain on your machine. Currently, the repository features integrated support for MiniMax-M2.7 for premium text planning, alongside WebSocket speech and asynchronous video generation paths. It also preserves a robust, zero-configuration "mock mode" so you never have to burn API credits just to test a workflow.
All long-running generation and rendering tasks are executed as local background jobs, ensuring a responsive UI and zero risk of HTTP timeouts without requiring external infrastructure like Redis or Celery.
Turning dense technical material into a good demo video is notoriously difficult. Engineers often have the core insights—detailed architecture diagrams, performance metrics, code snippets, and operational workflows—but struggle to compress them into a narrative that someone outside the immediate team can digest quickly.
Conversely, passing technical specs to non-technical agencies or standard AI video generators often results in high-gloss, low-signal marketing fluff that alienates developers. TechDemoForge exists to bridge this gap. It provides a structured pipeline designed specifically to maintain technical honesty—allowing infrastructure builders, developer tool creators, and researchers to author compelling storyboards and render them precisely without sacrificing technical credibility.
TechDemoForge focuses on technical honesty and structural precision. These visuals demonstrate the transition from engineering specs to verifiable video assets.
| 1. Source Ingestion | 2. MiniMax-M2.7 Storyboard |
|---|---|
 |
 |
| Ingest dense READMEs or specs. | MiniMax-M2.7 plans the narrative. |
| 3. Async Media Workers | 4. Final Render Output |
|---|---|
 |
 |
| Track jobs via persistent workers. | FFmpeg muxes the final artifacts. |
Tip
View the Full Pipeline Walkthrough to see the end-to-end flow from planning to MP4 export.
The engine uses a tiered architecture to isolate intelligence (LLMs) from orchestration and rendering.
graph TD
UI[Next.js Frontend] <--> API[FastAPI Backend]
API --> JM[Local Job Manager]
JM --> DB[(SQLite Metadata)]
API --> FS[Local Asset Filesystem]
subgraph Providers
MM[MiniMax Provider]
MOCK[Mock Provider]
end
API -- Select --> Providers
MM -- MiniMax-M2.7 --> Text[Planning]
MM -- WebSockets --> TTS[Speech]
MM -- Async REST --> T2V[Video]
JM --> FF[FFmpeg Engine]
FF --> MP4[Final Render]
The lifecycle of a technical demo follows a linear, verifiable path:
sequenceDiagram
participant User
participant App as TechDemoForge
participant Job as Background Worker
participant Provider
User->>App: Upload Source (README/Specs)
App->>Provider: Planning (MiniMax-M2.7)
Provider-->>App: JSON Storyboard
User->>App: Edit Storyboard Narrative
User->>App: Trigger Generation
App->>Job: Dispatch Media Task
Job->>Provider: Fetch Audio/Video Assets
Provider-->>Job: Binary Streams
App-->>User: Poll Progress Status
Job->>App: Mux & Render (FFmpeg)
App-->>User: Ready for Review
TechDemoForge is a local-first repository. It is structurally ready for the providers listed below, but it does not bundle API credentials.
The core narrative and storyboard planning is powered by MiniMax-M2.7.
- Anthropic Compatibility: MiniMax-M2.7 implements the Anthropic Messages API specification.
- Configuration: To use this engine, acquire a MiniMax API key and populate the
ANTHROPIC_API_KEYenvironment variable. EnsureANTHROPIC_BASE_URLpoints to the MiniMax endpoint (default is set in.env.example). - Why this matters: This allows us to use mature Anthropic client libraries while leveraging MiniMax’s technical intelligence.
A mandatory local dependency. If running locally (not in Docker), ensure the ffmpeg binary is on your system PATH or correctly specified in your .env.
The repository maintains a strict separation between the Frontend (TypeScript) and Backend (Python).
- Location:
shared/contracts/ - Synchronization: FastAPI exports OpenAPI to
shared/contracts/openapi.json, and TypeScript types are generated intoshared/contracts/openapi.ts. The frontend maps those API shapes into UI-friendly domain types inshared/contracts/project.ts. - Command:
cd frontend && npm run contracts:generate
The easiest way to run the full stack with all dependencies (including FFmpeg) bundled.
- Clone & Enter:
git clone https://github.com/manishklach/TechDemoForge.git cd TechDemoForge - Launch:
docker-compose up --build
- Access:
Open http://localhost:3000. The frontend proxies API requests to the
backendcontainer inter-vnet.
Best for development if you have Python 3.10+ and Node.js installed locally.
- Backend:
cd backend python -m venv venv source venv/Scripts/activate # Windows: venv\Scripts\activate pip install -r requirements.txt uvicorn app.main:app --port 8000
- Frontend:
cd frontend npm install npm run dev
- MiniMax-M2.7 Text Planning: Wired and active when configured. Uses Anthropic-compatible API.
- Speech Synthesis: Wired and active when configured. Supports raw audio extraction via the MiniMax WebSocket (
t2a_v2) streaming interface. - Video Generation: Wired and active when configured. targetting
MiniMax-Hailuo-02via async background workers. - Mock Mode: Fully functional zero-configuration fallback for offline testing.
When contributing screenshots or demo GIFs to docs/assets/:
- Resolution: 1280x720 (720p) is preferred for a balance of clarity and file size.
- GIF Duration: Keep walkthrough GIFs under 15 seconds; use high compression (e.g., via
ffmpegorezgif). - Formatting: Use descriptive names (e.g.,
01-ingestion.png) to maintain logical ordering in the documentation. - No Sensitive Data: Ensure all API keys and personal identifiers are redacted or cleared before capture.
See RELEASES.md for a detailed history of versions and changes.
Before tagging a release or merging a Tier-1 feature, verify the following stability markers:
- Docker Orchestration:
docker-compose up --buildlaunches cleanly; verify that the frontend proxies API requests to thebackendcontainer via the internal Next.jsrewritespath. - Mock Mode Sandbox: Ensure the engine completes a full planning-to-render cycle (Mock providers) with exactly zero API keys configured in
.env. - Job Persistence Audit: Trigger a generation task and refresh the browser multiple times; verify the job remains tracked and the UI resumes polling from the correct local filesystem state.
- Binary Integrity: Verify that generated MP4 artifacts (Mock or Real) are playable and correctly stored in the
backend/data/renders/directory. - Error Path Isolation: Provide an invalid API key; verify that the background job transitions to
failedand surfaces the specific provider error message in the UI.
This is an Alpha Release for developer evaluation.
- Stability: Core orchestration and job manager logic is stable; provider integration relies on external API availability.
- Data Model: Local-first; project and job metadata live in SQLite, while source files, generated media, subtitles, manifests, and render outputs stay on disk in
backend/data. - Design Goal: Prioritizes technical honesty and verifiable narrative structure over generic marketing-centric video generation.
The repository includes a lightweight backend verification layer aimed at confidence, not coverage theater.
backend/tests/test_mock_provider.py: deterministic mock provider contract checksbackend/tests/test_job_service.py: background job lifecycle and recovery behaviorbackend/tests/test_storage_metadata.py: SQLite metadata persistence for projects and jobsbackend/tests/test_pipeline_smoke.py: end-to-end mock smoke test through the API
Run it locally with:
cd backend
pytestMIT - See LICENSE for details.