Metadata-Version: 2.4
Name: vidforge
Version: 0.3.1
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
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
Requires-Dist: moviepy==1.0.3
Requires-Dist: requests>=2.28.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: python-dotenv>=0.20.0
Requires-Dist: edge-tts>=6.1.0
Requires-Dist: Pillow>=9.0.0
Requires-Dist: Flask>=2.0.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# VidForge 🚀 (AI 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 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
![VidForge Demo Output](vidforge/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 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

```bash
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](https://ffmpeg.org/download.html) and [ImageMagick](https://imagemagick.org/script/download.php) 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](https://www.pexels.com/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:
   ```bash
   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
```bash
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:

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

```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/)
