Metadata-Version: 2.1
Name: vidforge
Version: 0.4.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 🚀 (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 & 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

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

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

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


