vidforge 0.2.0

A powerful Python framework for fully automated AI video generation.

VidForge 🚀 (Python Video Automation Framework)

VidForge is an open-source Python framework 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 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:

• ImageMagick — auto-detected on macOS, Linux, and Windows:
  • macOS: brew install imagemagick
  • Ubuntu: sudo apt install imagemagick
  • Windows: download installer
• edge-tts — installed automatically as a dependency

---

⚡ Quickstart

Creating a fully automated video takes just 3 lines of Python code:

from vidforge import VideoFactory

# 1. Initialize the framework (reads PEXELS_API_KEY from env, or pass explicitly)
factory = VideoFactory(pexels_api_key="YOUR_PEXELS_API_KEY")

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

Or run the included example:

export PEXELS_API_KEY="your_key_here"
python3 examples/generate.py

---

⚙️ Advanced Configuration

Every aspect of the pipeline is customizable via VidForgeConfig:

from vidforge import VideoFactory, VidForgeConfig

config = VidForgeConfig(
    pexels_api_key="YOUR_KEY",
    tts_voice="en-US-ChristopherNeural",  # any edge-tts voice
    tts_rate="+15%",                       # speech speed
    font_size=80,                          # caption size
    font_color="yellow",                   # caption color
    text_position_y=1400,                  # caption vertical position
    bg_color_filter=0.5,                   # background darkening (0.0-1.0)
    fps=30,
    cleanup_temp=True,                     # auto-delete temp files
)

factory = VideoFactory(config=config)
factory.create_video("script.json", "output.mp4")

Config can also be driven entirely by environment variables:

export PEXELS_API_KEY="..."
export VIDFORGE_TTS_VOICE="en-US-JennyNeural"
export VIDFORGE_FONT_PATH="/path/to/font.ttf"

---

🛡️ Error Handling

All pipeline failures raise structured exceptions you can catch:

from vidforge import (
    VideoFactory, VidForgeError, ScriptValidationError,
    MediaFetchError, VoiceoverError, SyncError, RenderError,
)

try:
    factory.create_video("script.json", "out.mp4")
except ScriptValidationError as e:
    print(f"Bad script: {e}")
except MediaFetchError as e:
    print(f"Pexels failed: {e}")
except VidForgeError as e:
    print(f"Pipeline error: {e}")

Network requests include automatic retries with exponential backoff, and all temporary files are cleaned up even on failure.

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