🚀 VidForge Pro

VidForge Pro is an AI-powered framework that turns simple JSON scripts into fully-edited viral short-form videos. It automatically handles fetching high-quality background media (via Pexels), generating lifelike AI voiceovers (via edge-tts), syncing subtitles dynamically, and applying aesthetic text styles—all in a single click or command.

Whether you are a developer looking to automate content pipelines or a creator who wants a sleek visual editor to craft YouTube Shorts, TikToks, and Reels, VidForge has you covered.

✨ Features

• Automated Media Scraping: Fetches hyper-relevant 4K/HD videos or images from Pexels based on the scene context.
• AI Voiceovers (TTS): Built-in integration with edge-tts featuring dozens of realistic voices across multiple languages (English, Hindi, Spanish, French, German, Japanese, etc.).
• Voice Tuning: Customize TTS speed (rate) and voice tone (pitch) for highly engaging narrations.
• Dynamic Subtitling: Automatically generates word-by-word synced subtitles using Vosk speech recognition.
• Visual Scene Editor: A sleek, aesthetic Web UI built with Glassmorphism for easily adding scenes, tuning visuals, and previewing scripts without touching code.
• Two-Way JSON Sync: Edit visually using cards or directly manipulate the raw JSON script.
• Format Agnostic Output: Generates vertical .mp4 files perfectly formatted for Shorts/Reels.

⚙️ Installation & Setup

1. System Requirements

VidForge relies on MoviePy, which requires external system dependencies:

• FFmpeg: Required for all video/audio processing.
• ImageMagick: Required for generating subtitle text overlays.

On macOS (Homebrew):

brew install ffmpeg imagemagick

On Windows: Download and install FFmpeg and ImageMagick. Make sure both are added to your system's PATH.

2. Python Setup

Requires Python 3.9+. It is highly recommended to use a virtual environment.

# Clone or navigate to the directory
cd vidforge

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package and all dependencies
pip install -e .

3. Pexels API Key

You will need a free Pexels API key to fetch background videos and images.

1. Go to Pexels API
2. Create a free account and generate an API key.

🎨 Method 1: The Web UI (Recommended for Creators)

VidForge comes with a beautiful, responsive, and intuitive web application that makes generating videos incredibly easy.

1. Start the web server:

   python app.py
   

2. Open your browser and navigate to: http://localhost:8080
3. Configure: Enter your Pexels API Key (it will automatically save to your browser for next time!). Choose your voice, text color, media type (videos vs. images), and advanced voice pitch/rate settings.
4. Create: Use the Visual "Scene Editor" to add scenes, write your narration, and set background keywords.
5. Generate: Click "Generate Viral Video". The server will render it in the background and present you with a playable .mp4 and a download button!

💻 Method 2: The CLI (Recommended for Automation)

You can run VidForge entirely from the terminal for headless automation.

CLI Usage

vidforge --script examples/script.json --pexels YOUR_API_KEY --output final_short.mp4

CLI Arguments

📄 Script File Format (JSON)

VidForge reads your video structure from a simple JSON array of "scenes".

Example (script.json):

{
  "scenes": [
    {
      "keyword": "3d glowing brain scan",
      "text": "Never drink coffee within the first ninety minutes of waking up."
    },
    {
      "keyword": "3d cinematic clock time",
      "text": "When you wake up, your brain is filled with adenosine, the chemical that makes you tired."
    }
  ]
}

• keyword: Used to search Pexels for a highly relevant 4K/HD background video or image.
• text: The actual narration the AI Voice will read aloud, which will also be automatically timed and converted into on-screen subtitles.

🛠️ Project Structure

• vidforge/: The core framework containing the MediaScraper, VTTSyncEngine, and RenderingEngine.
• app.py: The Flask web server.
• templates/ & static/: HTML, CSS, and JS for the Web UI.
• vidforge/cli.py: The Command Line Interface entry point.

📝 License

MIT License. Feel free to use and modify.