Automated Video Generator
Transform text scripts into professional videos with AI voiceovers, stock footage, and Remotion rendering. Advanced features include direct filesystem access, environment management, and whitelisted command execution.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
Its scripts were only partly scanned.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/itsPremkumar/Automated-Video-Generator with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/itsPremkumar/Automated-Video-Generator'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/itspremkumar--automated-video-generator)HTML
<a href="/listings/itspremkumar--automated-video-generator"><img src="/api/listings/itspremkumar--automated-video-generator/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Choose your path:
| Path | Time | Difficulty | For | | -------------------------------------------------- | ----- | ---------- | ------------- | | [Windows Desktop App](#windows-desktop-app) | 2 min | ★☆☆ | Everyone | | [One-Click Launcher](#one-click-launcher-windows) | 3 min | ★☆☆ | Windows users | | [Manual Setup](#manual-setup) | 5 min | ★★☆ | Developers | | [Docker](#docker) | 3 min | ★★☆ | DevOps | | [npm (MCP)](#npm-mcp-server) | 1 min | ★☆☆ | AI agents |
🎬 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**.
<div align="center"> <br/> <em>Real Voicebox-narrated video from the pipeline. Script → voiceover + stock media → MP4, fully local.</em> </div>
🪟 Windows Desktop App
**No Node.js, Python, or terminal required.**
Download the [latest Windows installer](https://github.com/itsPremkumar/Automated-Video-Generator/releases/latest), 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" \
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/plugin.json · Manifest · 60 lines
- {
- "name": "Automated Video Generator",
- "version": "1.1.0",
- "description": "Transform text scripts into professional videos with AI voiceovers, stock footage, and Remotion rendering. Advanced features include direct filesystem access, environment management, and whitelisted command execution.",
- "icon": "video",
- "author": "Premkumar M (@itsPremkumar)",
- "repository": "https://github.com/itsPremkumar/Automated-Video-Generator",
- "license": "MIT",
- "components": {
- "skills": [
- {
- "name": "cli-operations",
- "path": ".agent/skills/cli-operations/SKILL.md"
- },
- {
- "name": "generate-script",
- "path": ".agent/skills/generate-script/SKILL.md"
- }
- ],
- "mcp": {
- "command": "npx",
- "args": ["-y", "tsx", "src/mcp-server.ts"],
- "env": ["PEXELS_API_KEY", "PIXABAY_API_KEY", "VIDEO_ORIENTATION", "VIDEO_VOICE"],
- "tools": [
- { "name": "generate_video", "description": "Generate a professional video from a text script." },
- { "name": "get_video_status", "description": "Check the status of a video generation job." },
- { "name": "list_jobs", "description": "List all recent video generation jobs." },
- { "name": "write_input_script", "description": "Save a video script to the input directory." },
- { "name": "read_input_script", "description": "Read available scripts from the input directory." },
- { "name": "delete_input_script", "description": "Remove a script from the input directory." },
- { "name": "validate_input_script", "description": "Check if a script format is valid." },
- { "name": "list_output_videos", "description": "List all generated videos." },
- { "name": "read_output_file", "description": "Read details or scene data from a completed video." },
- { "name": "delete_output", "description": "Delete a generated video and its assets." },
- { "name": "upload_asset", "description": "Upload media assets for use in videos." },
- { "name": "delete_asset", "description": "Remove a media asset." },
- { "name": "list_local_assets", "description": "List all uploaded media assets." },
- { "name": "run_pipeline_command", "description": "Run pipeline commands (generate, render, etc.)" },
- { "name": "read_env_config", "description": "View environment settings." },
- { "name": "update_env_config", "description": "Change environment settings." },
- { "name": "get_system_info", "description": "Check system and dependency status." },
- { "name": "health_check", "description": "Quick system health check." }
- ],
- "resources": [
- { "uri": "input://scripts", "name": "Input Scripts" },
- { "uri": "input://format", "name": "Script Format Guide" },
- { "uri": "output://videos", "name": "Output Videos List" },
- { "uri": "public://assets", "name": "Public Assets" },
- { "uri": "config://env", "name": "Environment Config" },
- { "uri": "config://pipeline", "name": "Pipeline Config" }
- ],
- "prompts": [
- { "name": "create-marketing-video", "description": "Workflow for marketing video creation." },
- { "name": "create-youtube-short", "description": "Workflow for viral YouTube Shorts." },
- { "name": "batch-generate", "description": "Workflow for batch video generation." },
- { "name": "debug-pipeline", "description": "Workflow for troubleshooting." }
- ]
- }
- }
- }
README.md · README · 643 lines
- <!--
- 🧠 Automated Video Generator
- SEO keywords: automated video generator, free video generator, open source video generator,
- ai video generator, text to video, remotion, edge tts, youtube shorts generator, tiktok
- video generator, faceless youtube, content automation, self hosted video generator,
- mcp server, model context protocol, stock media, pexels, pixabay, openverse, video pipeline,
- react video, nodejs video, typescript video, batch video generation, voiceover, text to speech,
- video creator, marketing video, explainer video, shorts automation, reels generator,
- open source, MIT license, programmatic video, no api key, cc images
- -->
- <!-- hero video removed per user request -->
- <div align="center">
- <h1>Automated Video Generator</h1>
- <p><strong>🆓 Free • 🔓 Open Source • 🏠 Self-Hosted • 🤖 AI Text-to-Video</strong></p>
- <p><b>Turn any script into a narrated, stock-footage video in minutes.</b><br/>No API key. No watermark. Runs 100% on your machine.</p>
- </div>
- <br/>
- <div align="center">
- <a href="https://github.com/itsPremkumar/Automated-Video-Generator/stargazers"><img src="https://img.shields.io/github/stars/itsPremkumar/Automated-Video-Generator?style=for-the-badge&logo=github" alt="GitHub stars"></a>
- <a href="https://github.com/itsPremkumar/Automated-Video-Generator/blob/main/LICENSE"><img src="https://img.shields.io/github/license/itsPremkumar/Automated-Video-Generator?style=for-the-badge" alt="MIT license"></a>
- <a href="https://github.com/itsPremkumar/Automated-Video-Generator/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/itsPremkumar/Automated-Video-Generator/ci.yml?branch=main&style=for-the-badge&label=CI" alt="CI status"></a>
- <a href="https://www.npmjs.com/package/automated-video-generator"><img src="https://img.shields.io/npm/v/automated-video-generator?style=for-the-badge&color=cb0000" alt="NPM version"></a>
- <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-18%2B-2f7d32?style=for-the-badge" alt="Node.js 18+"></a>
- <a href="https://github.com/itsPremkumar/Automated-Video-Generator/blob/main/docs/CONTRIBUTING.md"><img src="https://img.shields.io/badge/contributions-welcome-brightgreen?style=for-the-badge" alt="Contributions welcome"></a>
- <a href="https://github.com/itsPremkumar/Automated-Video-Generator/releases/latest"><img src="https://img.shields.io/badge/download-Windows_.exe-blue?style=for-the-badge&logo=windows" alt="Download Windows"></a>
- <a href="https://github.com/sponsors/itsPremkumar"><img src="https://img.shields.io/badge/Sponsor-%E2%9D%A4-red?style=for-the-badge&logo=github" alt="GitHub Sponsors"></a>
- </div>
- <div align="center">
- <a href="https://star-history.com/#itsPremkumar/Automated-Video-Generator&Date"><img src="https://api.star-history.com/svg?repos=itsPremkumar/Automated-Video-Generator&type=Date&theme=dark" alt="Star History Chart" width="600"></a>
- </div>
- <br/>
- ---
- ## 📖 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.
- <br/>
- <div align="center">
- <table>
- <tr>
- <td align="center"><b>🎬 Input</b></td>
- <td align="center"><b>⚙️ Pipeline</b></td>
- <td align="center"><b>📦 Output</b></td>
- </tr>
- <tr>
- <td align="center">Text script<br/>or JSON job<br/>or AI prompt</td>
- <td align="center">Parse → Fetch media<br/>→ Generate voiceover<br/>→ Render with Remotion</td>
- <td align="center">MP4 video<br/>+ Thumbnail<br/>+ Scene data</td>
- </tr>
- </table>
- </div>
- <br/>
- ---
- ## ✨ Demo
- > A real short generated by the pipeline (no re-render, no edits) — script in, MP4 out:
- <div align="center">
- <a href="https://github.com/itsPremkumar/Automated-Video-Generator">
- <img src="assets/demo/demo.gif" alt="Automated Video Generator — real pipeline output playing" width="360" style="border-radius: 12px; box-shadow: 0 4px 24px rgba(0,0,0,0.25);">
- </a>
- <br/>
- <em>▶️ Autoplaying: a real short generated by this pipeline (no re-render, no edits) — script in, MP4 out.</em>
- <br/><br/>
- <a href="https://github.com/itsPremkumar/Automated-Video-Generator">
- <img src="assets/demo/demo-showcase.png" alt="Automated Video Generator - Project Logo & GitHub Repository" width="100%" style="border-radius: 12px; box-shadow: 0 4px 24px rgba(0,0,0,0.25);">
- </a>
- <br/>
- <em>🎙️ Voiceover powered by <b>Voicebox Kokoro Heart</b> — realistic local AI narration. ✅ 32/32 quality checks passed on every output. 🔓 Free & open source.</em>
- </div>
- <div align="center">
- <img src="assets/diagrams/demo-flow.svg" alt="How it works: script → pipeline → video" width="720" style="border-radius: 12px; margin-top: 12px;">
- <br/>
- <em>Script → AI voiceover + stock media → MP4. Fully local.</em>
- </div>
- <hr/>
- ## 🚀 Quick Start (5 minutes)
- Choose your path:
- | Path | Time | Difficulty | For |
- | -------------------------------------------------- | ----- | ---------- | ------------- |
- | [Windows Desktop App](#windows-desktop-app) | 2 min | ★☆☆ | Everyone |
- | [One-Click Launcher](#one-click-launcher-windows) | 3 min | ★☆☆ | Windows users |
- | [Manual Setup](#manual-setup) | 5 min | ★★☆ | Developers |
- | [Docker](#docker) | 3 min | ★★☆ | DevOps |
- | [npm (MCP)](#npm-mcp-server) | 1 min | ★☆☆ | AI agents |
- ### 🎬 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.
- ```bash
- # 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**.
- <div align="center">
- <img src="assets/demo/demo.gif" alt="Real pipeline output — landscape render playing" width="640" style="border-radius: 12px; box-shadow: 0 4px 24px rgba(0,0,0,0.25);">
- <br/>
- <em>Real Voicebox-narrated video from the pipeline. Script → voiceover + stock media → MP4, fully local.</em>
- </div>
- ### 🪟 Windows Desktop App
- **No Node.js, Python, or terminal required.**
- Download the [latest Windows installer](https://github.com/itsPremkumar/Automated-Video-Generator/releases/latest), double-click, and the app opens the web portal automatically. Everything is bundled.
- ### 📜 One-Click Launcher (Windows)
- ```powershell
- .\Start-Automated-Video-Generator.bat
- ```
- Or the PowerShell version:
- ```powershell
- .\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
- ```bash
- # 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):
- ```bash
- 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`):
- ```bash
- 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):**
- | Var | Default | Purpose |
- |-----|---------|---------|
- | `PORT` | `3001` | Web portal / API port |
- | `PEXELS_API_KEY` | _(none)_ | Free stock video. Without it, falls back to Openverse / Wikimedia / Internet Archive. |
- | `YOUTUBE_API_KEY` | _(none)_ | YouTube metadata enrichment (optional). |
- | `OPENVERSE_ENABLED` | `true` | Use Openverse CC media when no API key is set. |
- | `TTS_PROVIDER` | `voicebox` | `voicebox` (default — vendored in-repo Kokoro/Chatterbox) or `edge-tts` (free, CPU). The pipeline auto-spawns the vendored backend. |
- | `VOICEBOX_ENGINE` | _(none)_ | `kokoro` or `chatterbox_turbo` — only when `TTS_PROVIDER=voicebox`. |
- | `VOICEBOX_PROFILE_ID` | _(none)_ | A Voicebox profile id (preset or cloned voice). |
- **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`](./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):**
- ```json
- {
- "mcpServers": {
- "automated-video-generator": {
- "command": "npx",
- "args": ["automated-video-generator"]
- }
- }
- }
- ```
- Or run it locally:
- ```bash
- 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:
- ```bash
- # 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`:
- ```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:
- ```bash
- 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](https://upload-post.com). This is **opt-in** — the batch CLI only posts when `--post` is passed AND the env vars are configured:
- ```bash
- # 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
- ```bash
- 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:
- ```json
- {
- "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
- | Feature | Description |
- | ---------------------------- | ----------------------------------------------------------------------------------------------- |
- | **🎤 400+ Voices** | Multi-language TTS via Voicebox (Kokoro, default) with Edge-TTS, XTTS fallback |
- | **🖼️ Stock Media** | Openverse + free CC sources (no key) + Pexels/Pixabay (set `PEXELS_API_KEY`/`PIXABAY_API_KEY` for higher relevance) + Wikimedia Commons + Internet Archive |
- | **🎵 Background Music** | Auto-ducking with volume control |
- | **🔄 Batch Processing** | Generate dozens of videos from one JSON file |
- | **🖥️ Web Portal** | Browser-based UI for generation, preview, download |
- | **🤖 MCP Server** | Connect Claude Desktop / Claude Code for AI-driven video creation |
- | **✅ AI Media Verification** | Validates visuals match scene context via Ollama moondream or Gemini Vision |
- | **🪟 Desktop App** | Standalone Windows .exe with bundled runtime |
- | **📱 Portrait + Landscape** | YouTube Shorts, TikTok, Reels, and widescreen support |
- | **↩️ Resumable Rendering** | Cancel and resume without losing progress |
- | **🎬 Remotion Studio** | Preview and tweak video compositions |
- | **🤖 Local AI Generation** | ComfyUI (SD1.5/SDXL), CogVideoX (T2V), AnimateDiff (I2V), Real-ESRGAN (upscale), rembg (bg removal) |
- | **🧠 AI Intelligence** | Beat-sync, CLIP semantic matching, script enhancement, multi-language subs, storyboard gen |
- | **🔌 AI Job Queue** | Serial AI processing — runs one AI job at a time (6GB RAM safe) |
- ---
- ## 🧠 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
- ```env
- MEDIA_VERIFICATION_ENABLED=true
- MEDIA_VERIFICATION_CONFIDENCE=6
- AI_PROVIDER=ollama
- ```
- [Full guide →](docs/MEDIA_VERIFICATION.md)
- ---
- ## 🔌 CLI Reference
- ```text
- 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:**
- ```bash
- # 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 →](docs/cli-reference.md)
- ---
- ## 🏗️ Architecture
- <div align="center">
- <img src="assets/diagrams/architecture.svg" alt="Hexagonal architecture: 4 runtimes, 1 core" width="760" style="border-radius: 12px; box-shadow: 0 4px 24px rgba(0,0,0,0.15);">
- </div>
- 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 →](docs/ARCHITECTURE.md)
- ---
- ## 🛠️ Use Cases
- ### YouTube Shorts / TikTok Automation
- Automate a daily Shorts channel. Generate 30 portrait-mode videos from a script list in one batch run.
- ```bash
- # Configure 30 scripts in input/scripts/input-scripts.json
- npm run generate
- ```
- [Example →](examples/youtube-shorts/)
- ### Faceless YouTube Channel
- Create documentary-style videos using stock footage, AI voiceovers, and background music — no camera or mic needed.
- [Example →](examples/faceless-channel/)
- ### Multi-Language Content
- Generate the same script in English, Tamil, Hindi, Spanish, French, and German — all from a single batch config.
- [Example →](examples/multi-language/)
- ### AI Agent Workflows
- Use the MCP server to let Claude or other AI agents create videos autonomously:
- ```bash
- # Start the MCP server
- npm run mcp
- # In Claude Code:
- claude mcp add automated-video-generator -- npx automated-video-generator
- ```
- [Example →](examples/mcp-agent/)
- ### 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 →](examples/local-assets/)
- [Full guide →](docs/INPUT_ASSETS_GUIDE.md)
- ### Background Music
- Add background music with auto volume ducking so voiceovers stay clear:
- ```env
- BACKGROUND_MUSIC=true
- BACKGROUND_MUSIC_VOLUME=0.15
- ```
- [Example →](examples/background-music/)
- ---
- ## 🌐 No-API-Key Media Sources
- One of the project's standout features: **you can generate videos without registering for any API service**.
- | Source | Needs API Key? | Content | Enabled By Default |
- | ---------------------------------- | ---------------- | ------------------------ | ------------------ |
- | [Pexels](https://pexels.com/api) | ✅ Free key | Stock videos + images | When key is set |
- | [Pixabay](https://pixabay.com/api) | ✅ Free key | Stock videos + images | When key is set |
- | **Openverse** | ❌ No key needed | 600M+ CC-licensed images | ✅ Yes |
- | **Wikimedia Commons** | ❌ No key needed | CC-licensed videos | ✅ Yes |
- | **Internet Archive** | ❌ No key needed | Public domain videos | ✅ Yes |
- [Openverse guide →](docs/OPENVERSE.md) | [Free video guide →](docs/FREE_VIDEO.md)
- ---
- ## 🆚 How It Compares
- | Feature | Automated Video Generator | Commercial tools | Other OSS tools |
- | -------------------------- | -------------------------- | ---------------- | --------------- |
- | **Price** | Completely free (MIT) | $20-200/mo | Varies |
- | **Watermark** | None | Usually yes | Varies |
- | **Self-hosted** | ✅ Yes | ❌ Cloud-only | Sometimes |
- | **Local execution** | ✅ Full local | ❌ | Sometimes |
- | **API key required** | ❌ Optional | ✅ Required | Varies |
- | **MCP / AI agent support** | ✅ Built-in | ❌ | Rare |
- | **Stock media** | ✅ Multi-source integrated | ✅ | Limited |
- | **AI media verification** | ✅ Built-in | ❌ | ❌ |
- | **400+ voices** | ✅ 13+ languages | ✅ | Limited |
- | **Batch mode** | ✅ Built-in | ✅ | Limited |
- | **Desktop app** | ✅ Windows (.exe) | ✅ | Rare |
- [Full comparison →](docs/COMPARISON.md)
- ---
- ## 📚 Documentation
- | Resource | Description |
- | ---------------------------------------------------- | ----------------------------------------- |
- | [Installation Guide](docs/installation.md) | Full setup instructions for all platforms |
- | [Configuration Reference](docs/configuration.md) | All environment variables explained |
- | [CLI Reference](docs/cli-reference.md) | All CLI commands and options |
- | [API Reference](docs/api-reference.md) | HTTP API endpoints |
- | [Architecture](docs/ARCHITECTURE.md) | Codebase architecture deep-dive |
- | [Usage Guide](docs/usage.md) | Generating videos step by step |
- | [FAQ](docs/faq.md) | Frequently asked questions |
- | [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
- | [OpenVerse Guide](docs/OPENVERSE.md) | Free CC-licensed image search |
- | [Free Video Guide](docs/FREE_VIDEO.md) | Free video sources |
- | [Media Verification](docs/MEDIA_VERIFICATION.md) | AI visual verification setup |
- | [Voice Cloning](docs/VOICE_CLONING_GUIDE.md) | Custom voice model setup |
- | [Input Assets Guide](docs/INPUT_ASSETS_GUIDE.md) | Using local images/videos |
- | [Production Hardening](docs/PRODUCTION_HARDENING.md) | Deployment best practices |
- | [Windows Installer](docs/WINDOWS_INSTALLER.md) | Desktop app builds |
- | [Claude MCP Setup](docs/CLAUDE_MCP_SETUP.md) | AI agent integration |
- | [llms.txt](llms.txt) | AI-friendly project summary |
- | [llms-full.txt](llms-full.txt) | Full AI-friendly documentation |
- ---
- ## 🤝 Contributing
- Contributions of all kinds are welcome — code, docs, bug reports, feature ideas, and community support.
- - [Contributing Guide](docs/CONTRIBUTING.md)
- - [Code of Conduct](docs/CODE_OF_CONDUCT.md)
- - [Security Policy](docs/SECURITY.md)
- - [Roadmap](docs/ROADMAP.md)
- - [Changelog](docs/CHANGELOG.md)
- ### Quick contributor workflow
- ```bash
- # 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 →](docs/ROADMAP.md)
- ---
- ## 📦 Releases
- The project follows [Semantic Versioning](https://semver.org/). See [releases](https://github.com/itsPremkumar/Automated-Video-Generator/releases) for download links and release notes.
- | Version | Status | Support |
- | ------- | ----------- | ----------------- |
- | 5.x | Active | ✅ Full support |
- | 4.x | Maintenance | ⚠️ Security fixes |
- | <4.0 | EOL | ❌ No support |
- ---
- ## 📄 License
- MIT © [Premkumar](https://github.com/itsPremkumar). See [LICENSE](LICENSE) for details.
- ---
- <div align="center">
- <p>
- <strong>⭐ Star this repo</strong> if it helps your projects — it helps others discover it too.<br/>
- <a href="https://github.com/itsPremkumar/Automated-Video-Generator">GitHub</a> •
- <a href="https://www.npmjs.com/package/automated-video-generator">npm</a> •
- <a href="https://itspremkumar.github.io/Automated-Video-Generator">Website</a> •
- <a href="https://github.com/itsPremkumar/Automated-Video-Generator/discussions">Discussions</a>
- </p>
- <p>
- <sub>Built with ❤️ and lots of ☕ | Free forever • MIT licensed • No watermarks • No subscriptions</sub>
- </p>
- </div>
src/adapters/mcp/pipeline-commands.test.ts · Bundled script · 188 lines · 2 findings marked
- import { test, mock } from 'node:test';
- import assert from 'node:assert/strict';
- /**
- * pipeline-commands.test.ts
- *
- * Tests the security-critical allowlist-based exec() in pipeline-commands.ts.
- *
- * Node 22 mock API constraint: mock.module() for a given specifier can only be
- * registered ONCE per process (no mock.resetModules(); restoreAll() does NOT free
- * it for re-registration). So child_process + fs are registered exactly ONCE at
- * top-level with mutable STATE the closures read at call time. Each test mutates
- * STATE before calling the SUT.
- *
- * NOTE: we must NOT do `(cp as any).exec = ...` / `mock.method(cp, 'exec', ...)` —
- * child_process.exec is a read-only ESM namespace export. mock.module() replaces
- * the whole namespace, which is the supported path.
- */
- const ALLOWED = ['generate', 'resume', 'segment', 'remotion:render', 'remotion:studio'];
- const execState: { impl: (cmd: string, cb?: (e: any, out: string, err: string) => void) => void } = {
- impl: (cmd: string, cb?: (e: any, out: string, err: string) => void) => {
- if (typeof cb === 'function') cb(null, `mock stdout for ${cmd}`, '');
- },
- };
- const fsState: { existsImpl: () => boolean; readImpl: () => string; writeImpl: () => void } = {
- existsImpl: () => false,
- readImpl: () => '{}',
- writeImpl: () => {},
- };
- mock.module('child_process', {
- namedExports: {
- execFile: mock.fn((file: string, args: string[], _opts: any, cb?: (e: any, out: string, err: string) => void) => {
- // Capture as a shell-style string so the test's execState.impl
- // (which pushes/inspects the command) keeps working.
- execState.impl(`${file} ${args.join(' ')}`, cb);
- return {} as any;
- }),
- },
- });
- mock.module('fs', {
- namedExports: {
- existsSync: () => fsState.existsImpl(),
- readFileSync: () => fsState.readImpl(),
- writeFileSync: (_path: string, _content: string) => fsState.writeImpl(),
- renameSync: () => {},
- },
- });
- // ---------------------------------------------------------------------------
- // Allowlist validation — pure logic, no mocking needed (throws before exec)
- // ---------------------------------------------------------------------------
- test('runPipelineCommand: rejects command not in allowlist', async () => {
- const { runPipelineCommand } = await import('./pipeline-commands.js');
- for (const bad of ['', 'rm -rf /', 'npm run generate', 'generate --danger', 'evil', 'ls', 'sudo']) {
- Note: Quoted as data in code: Runs `rm -rf` against a root or home-directory path
- Line 60 on GitHub
- await assert.rejects(
- () => runPipelineCommand(bad),
- { name: 'Error', message: /not whitelisted/ },
- `should reject "${bad}"`,
- );
- }
- });
- test('runPipelineCommand: error message lists all allowed commands', async () => {
- const { runPipelineCommand } = await import('./pipeline-commands.js');
- let captured: any;
- try {
- await runPipelineCommand('hack');
- } catch (err) {
- captured = err;
- }
- assert.ok(captured, 'should throw');
- assert.match(captured.message, /not whitelisted/);
- for (const cmd of ALLOWED) {
- assert.ok(captured.message.includes(cmd), `error message should mention "${cmd}"`);
- }
- });
- test('runPipelineCommand: rejects empty command', async () => {
- const { runPipelineCommand } = await import('./pipeline-commands.js');
- await assert.rejects(() => runPipelineCommand(''), { message: /not whitelisted/ });
- });
- // ---------------------------------------------------------------------------
- // Allowed commands — exec + fs mocked to prevent real execution
- // ---------------------------------------------------------------------------
- test('runPipelineCommand: allowed commands proceed and return correct shape', async () => {
- const execCalls: string[] = [];
- execState.impl = (cmd: string, cb?: (e: any, out: string, err: string) => void) => {
- execCalls.push(cmd);
- if (typeof cb === 'function') cb(null, 'mock stdout', '');
- };
- fsState.existsImpl = () => false;
- fsState.readImpl = () => '{}';
- fsState.writeImpl = () => {};
- const { runPipelineCommand } = await import('./pipeline-commands.js');
- for (const cmd of ALLOWED) {
- const result = await runPipelineCommand(cmd);
- assert.ok(result.jobId, `should return jobId for "${cmd}"`);
- assert.ok(result.jobId.startsWith('exec_'), 'jobId starts with exec_');
- assert.ok(result.command.includes(cmd), 'command includes the npm script');
- }
- assert.equal(execCalls.length, ALLOWED.length, 'every allowed command should have executed');
- });
- test('runPipelineCommand: allows passing arguments on allowed commands', async () => {
- const execCalls: string[] = [];
- execState.impl = (cmd: string, cb?: (e: any, out: string, err: string) => void) => {
- execCalls.push(cmd);
- if (typeof cb === 'function') cb(null, 'mock stdout', '');
- };
- fsState.existsImpl = () => false;
- fsState.readImpl = () => '{}';
- fsState.writeImpl = () => {};
- const { runPipelineCommand } = await import('./pipeline-commands.js');
- const result = await runPipelineCommand('generate', ['--batch', '--resume']);
- assert.ok(result.jobId);
- assert.ok(result.command.includes('--batch'));
- assert.ok(result.command.includes('--resume'));
- assert.ok(result.command.startsWith('npm run generate'));
- });
- test('runPipelineCommand: args with shell metacharacters do NOT bypass allowlist', async () => {
- const { runPipelineCommand } = await import('./pipeline-commands.js');
- await assert.rejects(() => runPipelineCommand('generate; rm -rf /', ['--flag']), { message: /not whitelisted/ });
- Note: Quoted as data in code: Runs `rm -rf` against a root or home-directory path
- Line 135 on GitHub
- });
- test('runPipelineCommand: each allowed command works with no args', async () => {
- const execCalls: string[] = [];
- execState.impl = (cmd: string, cb?: (e: any, out: string, err: string) => void) => {
- execCalls.push(cmd);
- if (typeof cb === 'function') cb(null, 'output', '');
- };
- fsState.existsImpl = () => false;
- fsState.readImpl = () => '{}';
- fsState.writeImpl = () => {};
- const { runPipelineCommand } = await import('./pipeline-commands.js');
- for (const cmd of ALLOWED) {
- const result = await runPipelineCommand(cmd);
- assert.ok(result.jobId, `no-args call should succeed for "${cmd}"`);
- }
- assert.equal(execCalls.length, ALLOWED.length);
- });
- test('runPipelineCommand: returns { jobId, command } shape', async () => {
- execState.impl = (cmd: string, cb?: (e: any, out: string, err: string) => void) => {
- if (typeof cb === 'function') cb(null, 'ok', '');
- };
- fsState.existsImpl = () => false;
- fsState.readImpl = () => '{}';
- fsState.writeImpl = () => {};
- const { runPipelineCommand } = await import('./pipeline-commands.js');
- const result = await runPipelineCommand('generate');
- assert.equal(typeof result.jobId, 'string');
- assert.equal(typeof result.command, 'string');
- assert.ok(result.jobId.length > 0);
- assert.ok(result.command.length > 0);
- });
- test('runPipelineCommand: executes the correct npm run command', async () => {
- const execCalls: string[] = [];
- execState.impl = (cmd: string, cb?: (e: any, out: string, err: string) => void) => {
- execCalls.push(cmd);
- if (typeof cb === 'function') cb(null, 'done', '');
- };
- fsState.existsImpl = () => false;
- fsState.readImpl = () => '{}';
- fsState.writeImpl = () => {};
- const { runPipelineCommand } = await import('./pipeline-commands.js');
- const result = await runPipelineCommand('remotion:render', ['vid-1']);
- assert.equal(result.command, 'npm run remotion:render -- vid-1');
- });
src/adapters/mcp/pipeline-commands.ts · Bundled script · 36 lines · 1 finding marked
- import { execFile, ChildProcess } from 'child_process';
- import { jobStore } from '../../infrastructure/persistence/job-store';
- import { resolveProjectPath } from '../../shared/runtime/paths';
- const ALLOWED_COMMANDS = ['generate', 'resume', 'segment', 'remotion:render', 'remotion:studio'];
- export async function runPipelineCommand(command: string, args: string[] = []) {
- if (!ALLOWED_COMMANDS.includes(command)) {
- throw new Error(`Command "${command}" is not whitelisted. Allowed: ${ALLOWED_COMMANDS.join(', ')}`);
- }
- // SECURITY: pass args as an argv array to execFile so they are NEVER
- // interpreted by a shell. The previous `exec(\`npm run ${command} -- ${args.join(' ')}\`)`
- // was a command-injection/RCE: a malicious `args` value like `"; rm -rf ~`
- Note: Quoted as data in code: Runs `rm -rf` against a root or home-directory path
- Line 14 on GitHub
- // would execute. npm receives the args verbatim as script flags.
- const jobId = `exec_${Date.now()}_${command}`;
- jobStore.set(jobId, { status: 'pending', progress: 0, message: `Running command: npm run ${command}` });
- const child: ChildProcess = execFile(
- 'npm',
- ['run', command, '--', ...args],
- { cwd: resolveProjectPath() },
- (error, stdout, stderr) => {
- if (error) {
- jobStore.set(jobId, { status: 'failed', error: error.message, message: stderr });
- return;
- }
- jobStore.set(jobId, { status: 'completed', progress: 100, message: stdout, endTime: Date.now() });
- },
- );
- // Return the full command string for callers/audit (informational only —
- // the actual execution above uses argv, not a shell).
- const commandStr = `npm run ${command}${args.length ? ' -- ' + args.join(' ') : ''}`;
- return { jobId, command: commandStr };
- }
Version history
v1.1.011/14/2026
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.