Metadata-Version: 2.1
Name: vidforge
Version: 0.2.0
Summary: A powerful Python framework for fully automated AI video generation.
Home-page: https://github.com/sundaradh/vidforge
Author: Sundar Adhikari
Author-email: sundaradh.dev@gmail.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# VidForge 🚀 (Python Video Automation Framework)

![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)
[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-Donate-yellow.svg)](https://buymeacoffee.com/sundaradh)

**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
![VidForge Demo Output](examples/vidforge_demo.gif)

## 🌟 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

```bash
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](https://imagemagick.org/script/download.php)
- **edge-tts** — installed automatically as a dependency

---

## ⚡ Quickstart

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

```python
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:

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

---

## ⚙️ Advanced Configuration

Every aspect of the pipeline is customizable via `VidForgeConfig`:

```python
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:

```bash
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:

```python
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:

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

---

## 🧠 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!

<a href="https://www.buymeacoffee.com/sundaradh" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>

---

## 📄 License
[MIT](https://choosealicense.com/licenses/mit/)


