Automated Video Generator

Setup Guide

This document explains how to set up the project for development, local rendering, and desktop packaging.

System Requirements

Runtime Overview

The project now supports four main runtime entrypoints that share one application core:

  1. Browser portal and HTTP API with npm run dev
  2. CLI generation with npm run generate
  3. MCP server with npm run mcp
  4. Windows desktop packaging with Electron

Current executable entry files:

For the architectural layout behind these entrypoints, see ARCHITECTURE.md.

Voice generation now follows this order when possible:

  1. Voicebox (vendored in-repo at src/speech/) — Kokoro/Chatterbox TTS, supports voice cloning, auto-started by pipeline
  2. Edge-TTS — fallback when Voicebox can’t start (missing venv, no GPU)
  3. Sine-tone — last resort fallback for silence detection

Development Setup

1. Install Node.js

Install Node.js from nodejs.org.

Verify:

node -v
npm -v

2. Install project dependencies

npm install

3. Install Python voice dependencies

Windows:

py -m pip install -r requirements.txt

If py is unavailable:

python -m pip install -r requirements.txt

macOS or Linux:

python3 -m pip install -r requirements.txt

This installs the edge-tts runtime used during normal development.

4. FFmpeg

The project prefers bundled ffmpeg-static and ffprobe-static, so many machines do not need a global FFmpeg install.

A system FFmpeg install is still useful as a fallback.

Verify if you have a global install:

ffmpeg -version

5. Configure environment variables

Copy .env.example to .env. For a full list of every variable and its default, see ENVIRONMENT.md.

Windows PowerShell:

Copy-Item .env.example .env

macOS or Linux:

cp .env.example .env

Set at least:

TTS_PROVIDER=voicebox
PEXELS_API_KEY=your_key_here
PIXABAY_API_KEY=
GEMINI_API_KEY=
PUBLIC_BASE_URL=
PORT=3001
VIDEO_ORIENTATION=portrait

TTS_PROVIDER defaults to voicebox (vendored in-repo backend at src/speech/). PEXELS_API_KEY is recommended for better stock media in the browser workflow.

Running The Project

Local browser portal

npm run dev

Open:

http://localhost:3001/

CLI generation

Create or update input/scripts/input-scripts.json, then run:

npm run generate

MCP server

npm run mcp

Use this runtime when connecting Claude Desktop, Claude Code, or other MCP clients.

Remotion Studio

npm run remotion:studio

Verification Commands

Backend and shared TypeScript

npx tsc -p tsconfig.json --noEmit

Electron main process

cmd /c node_modules\.bin\tsc.cmd -p tsconfig.electron.json --noEmit

Desktop bundle source check

npm run electron:verify-bundle

Unpacked Windows release check

npm run electron:verify-release

Health endpoint

Start the portal and open:

http://localhost:3001/api/health

The health response helps verify:

Desktop-Specific Notes

Setup wizard behavior

The Electron setup window is not just informational anymore.

Voice engine behavior on Windows

Packaged desktop builds try:

  1. bundled edge-tts.exe
  2. bundled Python -m edge_tts
  3. system edge-tts
  4. Windows offline speech voices
  5. Google TTS fallback if available

This makes fresh Windows installs much more resilient than before.

Render security default

Chromium web security is now enabled by default during Remotion render.

Only disable it if you have a specific compatibility issue:

set REMOTION_DISABLE_WEB_SECURITY=1

Use this only for debugging or controlled environments.

Troubleshooting

Edge-TTS works on your laptop but not on a fresh machine

That usually means your dev machine already had Python or edge-tts installed globally.

The current desktop app now reduces that problem by:

Voice engine still not available on Windows

Check:

Packaged render behaves differently than dev

Run:

npm run electron:verify-release

That checks the unpacked desktop build for the expected bundled runtime files.

This site is open source. Improve this page.