---

📖 What is this?

Automated Video Generator is a free, open-source, self-hosted pipeline that converts text scripts into polished MP4 videos. Give it a script — it fetches relevant stock visuals, generates natural voiceovers, synchronizes everything with Remotion, and exports a ready-to-share video.

No paid plans. No watermarks. No monthly limits. Just your machine, your scripts, and full control.

---

✨ Demo

A real short generated by the pipeline (no re-render, no edits) — script in, MP4 out:

---

🚀 Quick Start (5 minutes)

Choose your path:

🎬 Your first video in 2 commands

No API key required to run — Openverse + free CC sources provide stock footage out of the box. Voiceover uses the vendored Voicebox backend (Kokoro by default) with Edge-TTS fallback; the Kokoro backend needs a one-time setup — point VOICEBOX_PYTHON at a torch/kokoro venv (e.g. C:/one/voicebox/.venv/Scripts/python.exe) or it auto-falls back to the built-in Edge-TTS/Kokoro engine. Encoding is automatic: Windows uses h264_mf (Media Foundation, fast) and other platforms use libx264; --gpu selects AMF/NVENC/QSV when present. For best results set PEXELS_API_KEY (free): Pexels is the recommended provider and is skipped in keyless mode, so keyless runs use lower-relevance free sources.

# 1. Install (one time)
npm install

# 2. Generate (reads input/scripts/input-scripts.json, writes output/<id>/<Title>.mp4)
npm run generate

That's it. The CLI reads input/scripts/input-scripts.json (a sample job is pre-included) and renders an MP4 with AI voiceover + stock visuals + burned-in captions. With the bundled sample, find it at output/pre7_productivity_tip/One Simple Trick To Beat Procrastination.mp4.

Prefer a GUI? Run npm run dev and open http://localhost:3001 — paste a script, click Generate Video.

🪟 Windows Desktop App

No Node.js, Python, or terminal required.

Download the latest Windows installer, double-click, and the app opens the web portal automatically. Everything is bundled.

📜 One-Click Launcher (Windows)

.\Start-Automated-Video-Generator.bat

Or the PowerShell version:

.\Start-Automated-Video-Generator.ps1

The launcher auto-installs Node.js and Python (via winget), creates .env, installs dependencies, and opens the portal at http://localhost:3001.

🛠️ Manual Setup

Prerequisites: Node.js 18+, Python 3.8+, npm

# 1. Clone
git clone https://github.com/itsPremkumar/Automated-Video-Generator.git
cd Automated-Video-Generator

# 2. Install Node dependencies
npm install

# 3. Install Python voice engine
pip install -r requirements.txt

# 4. Configure environment
cp .env.example .env
# Edit .env — add PEXELS_API_KEY (free, get one at pexels.com/api)
# No API key? Set OPENVERSE_ENABLED=true (it's the default)

# 5. (Optional) Local AI generation — ComfyUI, CogVideoX, Real-ESRGAN, rembg
#    Install the AI providers you want (all optional, all free, all offline):
#    pip install diffusers transformers accelerate torch        # CogVideoX (T2V)
#    pip install realesrgan basicsr                            # Real-ESRGAN (upscale)
#    pip install rembg                                         # Background removal
#    git clone https://github.com/comfyanonymous/ComfyUI.git  # ComfyUI (image/I2V)

# 6. Start the web portal
npm run dev

Open http://localhost:3001/ — paste a script, click generate, and watch it render.

🐳 Docker

Pre-built image (built + scanned by CI, pushed to GHCR):

docker run -p 3001:3001 \
  -v "$(pwd)/input:/app/input" \
  -v "$(pwd)/output:/app/output" \
  ghcr.io/itspremkumar/automated-video-generator

Or build locally (pinned node:20-bookworm, full npm ci, edge-tts in a venv to satisfy PEP 668, platform linux/amd64, healthcheck on /api/health):

docker compose up --build

🚀 Production Deployment

The container is self-contained: it bundles the ffmpeg/ffprobe static binaries and a Python venv with edge-tts for free, key-less narration. No external services are required for the default pipeline.

Environment variables (all optional — sensible free defaults):

Voicebox (in-repo vendored, default narrator). Voicebox is vendored in-repo at src/speech/ (MIT, sourced from jamiepine/voicebox). It is the default TTS provider — the pipeline auto-spawns it as python -m speech.main using the in-repo venv. Kokoro (~800 MB VRAM) is the default narrator engine. If the backend cannot start (missing venv, no GPU), the pipeline degrades gracefully back to Edge-TTS. For voice cloning, set TTS_PROVIDER=voicebox and provide a VOICEBOX_PROFILE_ID. See docs/VOICEBOX_SETUP.md.

Health & hardening:

• Healthcheck hits GET /api/health (container HEALTHCHECK).
• No secrets are logged; output paths are sanitized against ../ traversal at the dispatch chokepoint (src/agentic/operations/security.ts).
• CI runs typecheck + test:unit + a Gitleaks secret scan + a Docker build/push to GHCR on every push to main.

The MCP server lets AI agents (Claude Desktop, Claude Code, Cursor, etc.) create videos autonomously — it exposes 61 tools across 7 families, 13 resources, and 4 prompts over stdio.

📚 See docs/MCP_TOOL_REFERENCE.md for the full tool-by-tool contract (auto-generated from source via npm run gen:mcp-doc; CI verifies it's in sync via npm run verify:mcp-doc).

Quick connect (read-only safe mode — default):

{
    "mcpServers": {
        "automated-video-generator": {
            "command": "npx",
            "args": ["automated-video-generator"]
        }
    }
}

Or run it locally:

npm install
npm run mcp        # starts the MCP server on stdio

⚠️ Safe mode (important): By default the MCP server runs in safe mode — read tools (read_input_script, list_output_videos, health_check, etc.) work, but all write/mutation tools are blocked with ForbiddenError: safe mode. This protects your files from accidental changes by an agent.

To enable write tools (write_input_script, delete_*, upload_asset, update_env_config, run_pipeline_command, delete_output), set the flag:

# one-off
ALLOW_UNSAFE_MCP_TOOLS=1 npm run mcp

# or in your client config (env)
{
  "mcpServers": {
    "automated-video-generator": {
      "command": "npx",
      "args": ["automated-video-generator"],
      "env": { "ALLOW_UNSAFE_MCP_TOOLS": "1" }
    }
  }
}

Only enable ALLOW_UNSAFE_MCP_TOOLS for trusted agents — it grants filesystem write access to your project.

What the server provides:

• Tools (60): write_input_script, read_input_script, delete_input_script, validate_input_script, upload_asset, delete_asset, list_output_videos, read_output_file, delete_output, generate_video, get_video_status, run_pipeline_command, list_jobs, get_batch_status, read_env_config, update_env_config, get_system_info, health_check, get_workspace_paths, list_public_files, list_voices, list_local_assets, search_free_video, download_free_video, agentic_plan, agentic_acquire, agentic_verify_all, list_pending_assets, get_asset_preview, approve_asset, reject_asset, agentic_gate, agentic_run, do_task, merge_videos, trim_video, crop_video, resize_video, rotate_video, extract_audio, split_video, add_captions, add_music, add_audio_track, localize_video, grade_video, slow_motion, speed_ramp, add_watermark, add_lower_third, add_progress_bar, derive_outputs, make_voiceover, download_image, download_video, remove_silence, detect_scenes, auto_reframe, reduce_noise, apply_brand_kit
• Resources (9): project overview, input scripts, input assets, input format docs, output videos, per-video detail, public tree, env/pipeline config
• Prompts (4): create-marketing-video, create-youtube-short, batch-generate, debug-pipeline

---

🎯 Generate Your First Video

CLI Batch Mode

Create input/scripts/input-scripts.json:

[
    {
        "id": "my-first-video",
        "title": "3 Productivity Habits That Actually Work",
        "orientation": "portrait",
        "language": "english",
        "script": "Here are three productivity habits that will change your life. First, start your day with a clear plan..."
    }
]

Run:

npm run generate

Output: output/my-first-video/final.mp4 🎉

Publishing to social (opt-in)

After a batch run, you can publish the rendered MP4s to TikTok, Instagram, or YouTube via upload-post.com. This is opt-in — the batch CLI only posts when --post is passed AND the env vars are configured:

# In .env (one-time):
UPLOAD_POST_ENABLED=true
UPLOAD_POST_API_KEY=your_upload-post_key
UPLOAD_POST_USERNAME=your_upload-post_user
UPLOAD_POST_PLATFORMS=tiktok,instagram   # or youtube,youtube_shorts

# Then:
npm run agentic:post    # alias for: agentic-batch --post

A publish-manifest.json is written next to each posted MP4 with the platform URL(s) and an audit trail. Failures never throw — one bad job can't kill the post step for the rest of the batch.

Web Portal

npm run dev
# Open http://localhost:3001

The portal lets you paste scripts, configure voice/language/orientation, track rendering progress live, and watch/download the result — all from your browser.

Director Mode

Use [Visual: ...] tags for frame-perfect scene control:

{
    "id": "director-mode-demo",
    "title": "My Directed Video",
    "script": "[Visual: a serene mountain lake at sunset, cinematic, slow pan]\nNestled in the heart of the Rockies, this view has inspired explorers for centuries."
}

---

🌟 Key Features

---

🧠 AI Visual Media Verification

After fetching media from stock sources, the pipeline verifies each image/frame against the scene description using a local vision model:

1. Image → base64 (or FFmpeg extracts a video frame)
2. Sent to Ollama (moondream) or Gemini Vision with a JSON verdict prompt
3. Low-confidence matches (< 6/10 default) are rejected, cached, and the file is deleted
4. Pipeline falls back to the next media source automatically

MEDIA_VERIFICATION_ENABLED=true
MEDIA_VERIFICATION_CONFIDENCE=6
AI_PROVIDER=ollama

Full guide →

---

🔌 CLI Reference

npm run generate              # Generate videos from input/scripts/input-scripts.json
npm run resume                # Resume an interrupted run
npm run segment               # Rebuild from existing scene data
npm run agentic               # Generate a video from a topic (agentic pipeline)
npm run agentic:batch         # Generate + verify multiple videos
npm run agentic:perspectives  # One topic → 5 editorial angles + comparison sheet
npm run doctor                # Pre-flight health check (ffmpeg/RAM/network/TTS)
npm run dev                   # Start the local web portal
npm run mcp                   # Start the MCP server
npm run typecheck             # TypeScript validation
npm run test                  # Typecheck + unit tests
npm run test:unit             # Run unit tests
npm run test:render           # Run E2E render test
npm run test:coverage         # Run tests with coverage
npm run lint                  # ESLint
npm run format                # Prettier formatting
npm run remotion:studio       # Open Remotion Studio for composition preview
npm run remotion:render       # Render using the Remotion pipeline
npm run electron:dev          # Run the desktop app in development mode
npm run electron:build        # Build the Windows desktop installer
npm run electron:pack         # Create unpacked release for testing
npm run docker:build          # Build Docker image
npm run docker:run            # Run Docker container
npm run batch                 # Batch mode alias
npm run agentic:upscale       # Upscale an image (AI, Real-ESRGAN)
npm run agentic:remove-bg     # Remove background (AI, rembg)

AI Tool Commands:

# Upscale an image 2x-4x using Real-ESRGAN
npx tsx src/adapters/cli/agentic-modular.ts upscale --input photo.jpg --output photo_4k.jpg --factor 2

# Remove background using rembg
npx tsx src/adapters/cli/agentic-modular.ts remove-bg --input photo.jpg --output photo_nobg.png --model u2net

Full CLI docs →

---

🏗️ Architecture

The project follows a hexagonal architecture with four entry points sharing a common application core.

• src/adapters/ — HTTP controllers, CLI runner, MCP tool registrars
• src/application/ — Shared orchestration services
• src/lib/ — Core business logic (fetchers, parsers, verifiers)
• src/infrastructure/ — Persistence and filesystem
• src/shared/ — Contracts, runtime safety, logging

Full architecture docs →

---

🛠️ Use Cases

YouTube Shorts / TikTok Automation

Automate a daily Shorts channel. Generate 30 portrait-mode videos from a script list in one batch run.

# Configure 30 scripts in input/scripts/input-scripts.json
npm run generate

Example →

Faceless YouTube Channel

Create documentary-style videos using stock footage, AI voiceovers, and background music — no camera or mic needed.

Example →

Multi-Language Content

Generate the same script in English, Tamil, Hindi, Spanish, French, and German — all from a single batch config.

Example →

AI Agent Workflows

Use the MCP server to let Claude or other AI agents create videos autonomously:

# Start the MCP server
npm run mcp

# In Claude Code:
claude mcp add automated-video-generator -- npx automated-video-generator

Example →

Local Assets

Use your own images and videos instead of stock media. Place files in input/visuals/ and reference them with [Visual: filename.mp4] or [Visual: filename.jpg].

Example → Full guide →

Background Music

Add background music with auto volume ducking so voiceovers stay clear:

BACKGROUND_MUSIC=true
BACKGROUND_MUSIC_VOLUME=0.15

Example →

---

🌐 No-API-Key Media Sources

One of the project's standout features: you can generate videos without registering for any API service.

Openverse guide →  |  Free video guide →

---

🆚 How It Compares

Full comparison →

---

📚 Documentation

---

🤝 Contributing

Contributions of all kinds are welcome — code, docs, bug reports, feature ideas, and community support.

• Contributing Guide
• Code of Conduct
• Security Policy
• Roadmap
• Changelog

Quick contributor workflow

# Fork → Clone → Branch → Code → Test → PR
git checkout -b feat/my-feature
# ... make changes ...
npm run typecheck && npm run test:unit && npm run lint && npm run format
git push origin feat/my-feature
# Open a pull request

---

🗺️ Roadmap

Current (v5.x): Desktop app, MCP server, AI verification, GPU acceleration, free media sources, voice cloning, content gate, subtitle sidecars, batch mode presets

Short-term (v5.5-v6.0): Plugin system, subtitle styling, template system, macOS/Linux desktop, Swagger docs

Medium-term (v6.0-v7.0): Visual timeline editor, collaboration, advanced transitions

Long-term (v7.0+): Cloud rendering, marketplace, storyboard AI, mobile companion

Full roadmap →

---

📦 Releases

The project follows Semantic Versioning. See releases for download links and release notes.

---

📄 License

MIT © Premkumar. See LICENSE for details.

---