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 & Features

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.

🔥 NEW: Professional Editing Features

• Advanced Text Styling: Full control over font size, stroke width, text colors, and shadow box opacity.
• Dynamic Word Grouping: Choose exactly how many words flash on screen per subtitle chunk (e.g., fast-paced 4-word bursts).
• Background Music (BGM): Automatically mix in your own audio tracks with intelligent volume ducking behind the AI voice.
• Cinematic Effects: Automatic smooth crossfades between scenes and slow Ken Burns zoom effects for image backgrounds.
• Bulk Generation: Generate entire directories of JSON scripts at once, completely headless or via the Web UI!

---

💻 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. Advanced Settings: Customize your video with options for Background Media, Darkness filter, Font Size, Stroke Width, Word Grouping, Voice Pitch, and more!
5. Add Music: Click to browse and upload your own background .mp3 or .wav track.
6. Generate: Click "Generate Viral Video".

📁 Web UI Bulk Generation

Don't want to click generate one by one? In the Web UI, click the "Bulk Videos" tab at the bottom to drag-and-drop multiple JSON files. The engine will queue them up and render all of them into your local vidforge_output/ folder!

---

💻 Method 2: The CLI (Recommended for Automation)

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

Single Video

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

Bulk Video Generation (New!)

Got a folder full of scripts? Process them all in one command:

vidforge --script ./my_script_folder/ --pexels YOUR_API_KEY

Argument	Description	Default
--script	Path to the JSON script file OR a directory of JSON scripts (Required)	None
--pexels	Your Pexels API Key (Required)	None
--output	The name of the final rendered video file (ignored in bulk mode)	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 (with advanced options)
config = VidForgeConfig(
    pexels_api_key="YOUR_PEXELS_API_KEY",
    tts_voice="en-US-ChristopherNeural",  # any edge-tts voice
    tts_rate="+10%",                       # fast-paced speech
    font_color="yellow",                   # viral caption color
    font_size=80,                          # large text
    stroke_width=3,                        # clean black outline
    words_per_subtitle=4,                  # Alex Hormozi style pacing
    bg_color_filter=0.55,                  # cinematic darkness
    bg_music_path="./lofi_beat.mp3",       # background music
    bg_music_volume=0.1,
    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