Metadata-Version: 2.4
Name: vidforge
Version: 0.3.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
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 Pro

VidForge Pro is an AI-powered framework that turns simple JSON scripts into fully-edited viral short-form videos. It automatically handles fetching high-quality background media (via Pexels), generating lifelike AI voiceovers (via edge-tts), syncing subtitles dynamically, and applying aesthetic text styles—all in a single click or command.

Whether you are a developer looking to automate content pipelines or a creator who wants a sleek visual editor to craft YouTube Shorts, TikToks, and Reels, VidForge has you covered.

---

## ✨ Features

- **Automated Media Scraping**: Fetches hyper-relevant 4K/HD videos or images from Pexels based on the scene context.
- **AI Voiceovers (TTS)**: Built-in integration with `edge-tts` featuring dozens of realistic voices across multiple languages (English, Hindi, Spanish, French, German, Japanese, etc.).
- **Voice Tuning**: Customize TTS speed (rate) and voice tone (pitch) for highly engaging narrations.
- **Dynamic Subtitling**: Automatically generates word-by-word synced subtitles using Vosk speech recognition.
- **Visual Scene Editor**: A sleek, aesthetic Web UI built with Glassmorphism for easily adding scenes, tuning visuals, and previewing scripts without touching code.
- **Two-Way JSON Sync**: Edit visually using cards or directly manipulate the raw JSON script.
- **Format Agnostic Output**: Generates vertical `.mp4` files perfectly formatted for Shorts/Reels.

---

## ⚙️ Installation & Setup

### 1. 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.

**On macOS (Homebrew):**
```bash
brew install ffmpeg imagemagick
```

**On Windows:**
Download and install [FFmpeg](https://ffmpeg.org/download.html) and [ImageMagick](https://imagemagick.org/script/download.php). Make sure both are added to your system's `PATH`.

### 2. Python Setup
Requires Python 3.9+. It is highly recommended to use a virtual environment.

```bash
# Clone or navigate to the directory
cd vidforge

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package and all dependencies
pip install -e .
```

### 3. Pexels API Key
You will need a free Pexels API key to fetch background videos and images.
1. Go to [Pexels API](https://www.pexels.com/api/)
2. Create a free account and generate an API key.

---

## 🎨 Method 1: The Web UI (Recommended for Creators)

VidForge comes with a beautiful, responsive, and intuitive web application that makes generating videos incredibly easy.

1. Start the web server:
   ```bash
   python app.py
   ```
2. Open your browser and navigate to: `http://localhost:8080`
3. **Configure**: Enter your Pexels API Key (it will automatically save to your browser for next time!). Choose your voice, text color, media type (videos vs. images), and advanced voice pitch/rate settings.
4. **Create**: Use the Visual "Scene Editor" to add scenes, write your narration, and set background keywords.
5. **Generate**: Click "Generate Viral Video". The server will render it in the background and present you with a playable `.mp4` and a download button!

---

## 💻 Method 2: The CLI (Recommended for Automation)

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

### CLI Usage
```bash
vidforge --script examples/script.json --pexels YOUR_API_KEY --output final_short.mp4
```

### CLI Arguments
| 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` |
| `--fps` | The frames per second for the output video | `30` |

---

## 📄 Script File Format (JSON)

VidForge reads your video structure from a simple JSON array of "scenes". 

**Example (`script.json`):**
```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."
    }
  ]
}
```
- **`keyword`**: Used to search Pexels for a highly relevant 4K/HD background video or image.
- **`text`**: The actual narration the AI Voice will read aloud, which will also be automatically timed and converted into on-screen subtitles.

---

## 🛠️ Project Structure
- `vidforge/`: The core framework containing the `MediaScraper`, `VTTSyncEngine`, and `RenderingEngine`.
- `app.py`: The Flask web server.
- `templates/` & `static/`: HTML, CSS, and JS for the Web UI.
- `vidforge/cli.py`: The Command Line Interface entry point.

## 📝 License
MIT License. Feel free to use and modify.
