vidforge 0.3.1

A powerful Python framework for fully automated AI video generation.

VidForge 🚀 (AI Video Automation Framework)

VidForge is an open-source Python framework and beautiful Web UI engineered to convert simple JSON scripts into fully-edited, highly-engaging short-form videos (TikTok, Instagram Reels, YouTube Shorts) with absolutely zero manual video editing required.

Built for backend developers, indie hackers, and automation engineers.

🎥 See it in Action

🌟 Core Architecture

VidForge is separated into three hyper-optimized modules:

1. MediaScraper: Asynchronously hits the Pexels REST API to pull 4K cinematic background videos or images based on NLP keywords, and interfaces with the Edge-TTS engine for premium voiceovers.
2. VTTSyncEngine: Mathematically parses .vtt timestamp files to map exact millisecond audio triggers to visual text components.
3. RenderingEngine: Utilizes moviepy to automatically composite TikTok-optimized (1080x1920) clips, apply cinematic color grading, and render "Alex Hormozi style" Word-Pop text animations dynamically.

---

💻 Installation

pip install vidforge

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.
  • macOS: brew install ffmpeg imagemagick
  • Ubuntu: sudo apt install ffmpeg imagemagick
  • Windows: Download FFmpeg and ImageMagick and add to PATH.

---

🔑 Getting a Pexels API Key

VidForge uses Pexels to fetch high-quality background videos. You will need a free API key to use it:

1. Go to Pexels API and sign up for a free account.
2. Once logged in, navigate to Your API Key in the API section.
3. Generate a new API key and copy it. You will use this key as PEXELS_API_KEY in your environment variables or in the Web UI.

---

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

VidForge comes with a beautiful, responsive, and intuitive web application built with Glassmorphism for visually building scripts.

1. Once installed via pip, simply run this command in your terminal:

   vidforge-web
   

2. Open your browser and navigate to: http://localhost:8080
3. Configure: Enter your Pexels API Key (it will automatically save to your browser).
4. Generate: Click "Generate Viral Video". The server will safely save your rendered .mp4 into a local vidforge_output/ folder!

---

💻 Method 2: The CLI (Recommended for Automation)

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

CLI Usage

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

Argument	Description	Default
--script	Path to the JSON script file (Required)	None
--pexels	Your Pexels API Key (Required)	None
--output	The name of the final rendered video file	output.mp4
--voice	The edge-tts voice ID to use (e.g. en-US-ChristopherNeural)	en-US-ChristopherNeural
--font-color	The hex code for the subtitle text color	yellow
--media-type	Use video or image for backgrounds	video

---

🐍 Method 3: The Python API (Recommended for Developers)

Creating a fully automated video in your own Python script takes just 3 lines of code:

from vidforge import VideoFactory, VidForgeConfig

# 1. Configure the engine
config = VidForgeConfig(
    pexels_api_key="YOUR_PEXELS_API_KEY",
    tts_voice="en-US-ChristopherNeural",  # any edge-tts voice
    tts_rate="+15%",                       # speech speed
    font_color="yellow",                   # caption color
    fps=30
)

# 2. Initialize the framework 
factory = VideoFactory(config=config)

# 3. Build the Video!
factory.create_video(
    script_json_path="script.json",
    output_filename="viral_video.mp4"
)

All pipeline failures raise structured exceptions you can catch (e.g. ScriptValidationError, MediaFetchError, VidForgeError).

---

📄 The script.json Format

The engine expects a highly structured JSON array where you map your spoken text to specific background aesthetic keywords:

{
  "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."
    }
  ]
}

🧠 Why I Built This

This package was built to completely eliminate the bottleneck of manual video editing using Adobe Premiere or CapCut. By treating video generation as a standard API-driven software engineering problem, VidForge allows you to scale content creation infinitely using standard Python loops.

🤝 Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

☕ Support the Project

If this framework saved you hours of manual video editing, consider buying me a coffee to support future open-source development!

---

📄 License

MIT