# 🎬 YouTube Factory — Self-Hosted 24/7 Faceless Video Pipeline

An autonomous, distributed 3-PC AI pipeline for generating broadcast-quality faceless YouTube documentaries in both **English and Spanish**, complete with dynamic A/B thumbnails, chapters, background music, stock footage integration, and ready-to-upload bundles.

---

## 🏗️ 3-PC Architecture

| PC | OS | Hardware | Role | APIs & Ports |
|---|---|---|---|---|
| **AMDLLM** | Arch Linux | RX 9060 XT 8GB + 64GB RAM | Script Generation, Translation, Trending Topics | `llama.cpp` (:8002), `ComfyUI` (:8188) |
| **NvidiaLLM** | Arch Linux | RTX 5060 Ti 16GB + RTX 4060 8GB | AI Video (MiniMax H3), AI Images (SDXL/z-image), Thumbnails | `ComfyUI` (:8188) |
| **IntelLLM** | Ubuntu 24.04 | Arc A770 16GB + 32GB RAM | Bilingual TTS (Kokoro), Whisper Subtitles, FFmpeg Assembly | `Kokoro TTS` (:8003) |

```
┌────────────────────────────────────────────────────────────────────────────────────────┐
│                                 ORCHESTRATOR & 24/7 ENGINE                             │
│  • Topic Modes: Single (--topic), Batch (--batch), Live Trending (--trending)          │
│  • 24/7 Daemon Worker (--daemon) with SQLite Queue & Fault-Tolerant Checkpoints        │
│  • YouTube Uploader Readiness (YouTube Data API v3 OAuth2 + Metadata + Captions)       │
└────────────────────────────────────────────────────────────────────────────────────────┘
                                     │
         ┌───────────────────────────┼───────────────────────────┐
         ▼                           ▼                           ▼
┌──────────────────┐       ┌──────────────────┐       ┌──────────────────┐
│ AMDLLM (port 8002)│       │NvidiaLLM (port 8188│       │IntelLLM (port 8003│
│ 10.4.0.181       │       │ 10.4.0.180       │       │ 10.4.0.182       │
├──────────────────┤       ├──────────────────┤       ├──────────────────┤
│ • llama.cpp LLM  │       │ • ComfyUI        │       │ • Kokoro TTS     │
│ • Qwen3.5-7B     │       │ • MiniMax H3 T2V │       │   (EN & ES)      │
│ • Scriptwriting  │       │ • z-image-turbo  │       │ • faster-whisper │
│ • Translation    │       │ • SDXL Checkpoint│       │   subtitles      │
│ • SEO & Chapters │       │ • A/B Thumbnails │       │ • FFmpeg Engine  │
│ • Trending Ideas │       │ • Stock Media    │       │ • Audio Ducking  │
└──────────────────┘       └──────────────────┘       └──────────────────┘
```

---

## 🚀 Usage & CLI Commands

### 1. Health Check
Verify network and AI services on all 3 PCs:
```bash
python3 youtube_factory.py --health
```

### 2. Single Video Generation
Generate a complete bilingual video bundle for a specific topic:
```bash
python3 youtube_factory.py --topic "The Secret History of the Roman Empire"
```
Custom duration (e.g. 2 minutes / 120 seconds):
```bash
python3 youtube_factory.py --topic "SpaceX Starship" --duration 120
```

### 3. Batch Processing
Process multiple topics sequentially:
```bash
python3 youtube_factory.py --batch \
  "Why Cats Dominated Ancient Egypt" \
  "The Lost City Under the Sahara" \
  "How Chocolate Changed the World"
```
Or load topics from a text file:
```bash
python3 youtube_factory.py --batch-file topics.txt
```

### 4. Live Trending Topics Discovery
Automatically discover real-time Google Trends & YouTube viral topics:
```bash
# General real-time trends
python3 youtube_factory.py --trending --trending-count 3

# Niche-specific viral brainstorming (space, history, science, tech, mysteries, business)
python3 youtube_factory.py --trending --trending-niche space --trending-count 5
```

### 5. 24/7 Autonomous Daemon Mode
Run the pipeline continuously 24/7. When the queue is empty, the daemon autonomously discovers new trending topics, generates the scripts, visuals, voiceovers, thumbnails, and packages:
```bash
python3 youtube_factory.py --daemon
```

### 6. Background Queue Management
Add and monitor jobs in the persistent SQLite queue:
```bash
# Add a topic to the queue
python3 youtube_factory.py --queue-add "The Voynich Manuscript" --duration 180

# View queue status and history
python3 youtube_factory.py --queue-list

# Retry all failed jobs
python3 youtube_factory.py --queue-retry
```

### 7. Dry Run (Metadata & Prompt Verification)
Generate the script, translations, chapters, SEO descriptions, and visual prompts without running GPU video rendering:
```bash
python3 youtube_factory.py --topic "Deep Ocean Mysteries" --dry-run
```

---

## 🎨 Visual Generation & Stock Media

The pipeline utilizes an intelligent multi-tier visual engine:
1. **AI Video Generation**: NvidiaLLM ComfyUI `MiniMax H3` text-to-video (768x432 24fps, capped at ~6.5s per clip for speed).
2. **Internet Stock Footage & Photos**: Direct HD downloaders for Wikimedia Commons (enabled by default) and Pexels / Pixabay APIs (keys in config).
3. **AI Images with Ken Burns Motion**: Generates 16:9 SDXL / z-image-turbo images and applies dynamic pan/zoom motion effects via FFmpeg.
4. **Configurable Strategy** in `factory_config.yaml`:
   - `hybrid`: True 4-way rotation per segment — AI video → stock video → AI image (Ken Burns) → stock image (Ken Burns) — with each source falling back to the next on failure.
   - `all_ai`: Prioritizes MiniMax H3 AI video for every segment.
   - `stock_focused`: Prioritizes real-world stock video/photo b-roll.

Every visual is normalized to **exactly its narration segment's duration** (short clips
are looped, long clips trimmed, stills animated), so picture and voiceover stay in sync.
If a ComfyUI generation times out, the job is cancelled server-side so stuck jobs never
clog the queue for later segments.

---

## 🎵 Background Music & Audio Ducking

- **Procedural Cinematic Soundtracks**: Synthesizes custom multi-layered ambient/cinematic audio scores tailored to the exact length of the video (ambient pads, minor chord progressions, deep sub-bass, atmospheric textures).
- **Active Audio Ducking**: IntelLLM FFmpeg applies `sidechaincompress` to dynamically duck background music by ~18dB whenever the narrator speaks, allowing the voiceover to remain punchy and crystal clear.

---

## 🖼️ A/B Testing Thumbnails & Chapters

For every generated video, the pipeline outputs:
- **3 Visual Concepts (A, B, C)** generated via ComfyUI / high-res visual assets.
- **English Title Overlays** (`thumb_A_en.png`, `thumb_B_en.png`, `thumb_C_en.png`) with bold modern typography and high-contrast styling.
- **Spanish Title Overlays** (`thumb_A_es.png`, `thumb_B_es.png`, `thumb_C_es.png`).
- **Clean Backgrounds** (`thumb_A_clean.png`, etc.) without text.
- **Clickable YouTube Chapters** (`00:00 - Intro`, `00:45 - The Discovery`, etc.) calculated from exact voiceover timestamps and embedded into video descriptions.

---

## 📁 Output Bundle Structure

Every completed video creates an upload-ready package in `output/`:

```
output/
├── 1786872000_Roman_Empire_en.mp4              # English master video (voice + music + subs)
├── 1786872000_Roman_Empire_es.mp4              # Spanish master video (voice + music + subs)
├── 1786872000_Roman_Empire_subtitles_en.srt   # English standalone SRT caption track
├── 1786872000_Roman_Empire_subtitles_es.srt   # Spanish standalone SRT caption track
├── 1786872000_Roman_Empire_thumb_A_en.png     # Concept A Thumbnail (English text)
├── 1786872000_Roman_Empire_thumb_A_es.png     # Concept A Thumbnail (Spanish text)
├── 1786872000_Roman_Empire_thumb_A_clean.png  # Concept A Thumbnail (Clean background)
├── 1786872000_Roman_Empire_thumb_B_en.png
├── 1786872000_Roman_Empire_thumb_C_en.png
├── 1786872000_Roman_Empire_meta.json          # Complete JSON manifest for YouTube API
├── 1786872000_Roman_Empire_upload_EN.txt      # Formatted copy-paste bundle (YouTube Studio)
└── 1786872000_Roman_Empire_upload_ES.txt      # Formatted copy-paste bundle in Spanish
```

---

## 📤 YouTube API Automated Uploads

To enable automated video uploading:
1. Download OAuth credentials from Google Cloud Console as `client_secrets.json` and place it in the project root.
2. Run manual upload for any completed job:
   ```bash
   python3 youtube_factory.py --upload output/1786872000_Roman_Empire_meta.json
   ```
3. Or set `auto_upload: true` in `factory_config.yaml` to upload videos automatically upon generation.

---

## ⚙️ Configuration (`factory_config.yaml`)

```yaml
pcs:
  amdllm:   { host: "10.4.0.181", ssh_user: "mark" }
  nvidiam:  { host: "10.4.0.180", ssh_user: "mark" }
  intelllm: { host: "10.4.0.182", ssh_user: "mark" }

pipeline:
  duration_seconds: 180
  visual_strategy: "hybrid" # "hybrid", "all_ai", "stock_focused"
  voices:
    en: "af_heart"
    es: "ef_dora"
  thumbnail_count: 3
  music_mood: "cinematic"
  pexels_api_key: ""
  pixabay_api_key: ""

daemon:
  poll_interval_seconds: 30
  auto_trending_when_empty: true
  trending_niche: ""

youtube:
  client_secrets_file: "client_secrets.json"
  token_file: "youtube_token.json"
  default_privacy: "private"
  auto_upload: false
```

---

**License:** Apache 2.0