commit 52944843f1f821f8cf45a4ca7103221accc55a78
Author: badmark <badmark@gmail.com>
Date:   Sun Aug 16 09:37:06 2026 -0600

    first commit

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..341aac3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,211 @@
+# 🎬 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