🎬 VideoNut

🚀 Create Professional YouTube Documentaries with AI Agents

10 Specialized AI Agents | Multi-CLI Support | Zero Manual Research | Production-Ready Assets

📦 Install • 🎯 Quick Start • 🤖 Agents • 📖 Docs • 🤝 Contribute

⚡ One Command Setup

npx videonut init

That's it! This automatically installs Python, FFmpeg, Gemini CLI, and all dependencies.

🎯 What is VideoNut?

VideoNut transforms your ideas into production-ready YouTube documentaries using 10 specialized AI agents:

📡 Topic Scout → 🎯 Prompt → 🕵️ Investigator → ✍️ Scriptwriter → 🎬 Director
        ↓
    🦅 Scavenger → 💾 Archivist → 🧐 EIC → 🎨 Thumbnail → 🔍 SEO

What You Get:

| Output | Description | |--------|-------------| | 📋 Research Dossier | Fully sourced facts with YouTube video timestamps | | ✍️ Complete Script | Word-count matched narration for your target duration | | 🎬 Visual Direction | Shot-by-shot guide with asset links | | 📦 Downloaded Assets | Video clips, screenshots, PDFs ready for editing | | 🎨 Thumbnail Prompts | AI image generation prompts for click-worthy thumbnails | | 🔍 SEO Package | Optimized titles, descriptions, tags for YouTube |

📦 Quick Install

⚠️ Prerequisites: Install Node.js First

VideoNut requires Node.js 20+ to run. Choose one method to install:

1. Go to nodejs.org
2. Download the LTS version (recommended)
3. Run the installer and follow the prompts
4. Restart your computer
5. Verify installation: node --version and npm --version

Windows (PowerShell as Administrator):

winget install OpenJS.NodeJS.LTS

macOS:

brew install node

Linux (Ubuntu/Debian):

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Option 1: NPX (Recommended)

mkdir my-documentary
cd my-documentary
npx videonut init

Option 2: Clone from GitHub

git clone https://github.com/konda-vamshi-krishna/videonut.git
cd videonut
npm run setup

Both methods automatically install:

• ✅ Python (if not installed)

• ✅ FFmpeg & FFprobe

• ✅ Gemini CLI (or your choice)

• ✅ All Python dependencies

🚀 Quick Start

After installation, open your AI CLI and run:

# Start with Gemini CLI
gemini

# Then run your first agent
/topic_scout

Agent Pipeline

| # | Agent | Command | What It Does | |---|-------|---------|--------------| | 1 | 📡 Topic Scout | /topic_scout | Find trending topics, create project | | 2 | 🎯 Prompt | /prompt | Generate research questions | | 3 | 🕵️ Investigator | /investigator | Deep research with sources | | 4 | ✍️ Scriptwriter | /scriptwriter | Write narration script | | 5 | 🎬 Director | /director | Create visual directions | | 6 | 🦅 Scavenger | /scavenger | Find and verify assets | | 7 | 💾 Archivist | /archivist | Download all assets | | 8 | 🧐 EIC | /eic | Final quality review | | 9 | 🎨 Thumbnail | /thumbnail | Generate thumbnail prompts | | 10 | 🔍 SEO | /seo | YouTube optimization |

🤖 Meet the Agents

| Agent | Persona | What They Do | |-------|---------|--------------| | Scout | Trend Hunter | Finds viral topics, checks YouTube competition | | Prompt | Research Architect | Creates focused research questions | | Sherlock | Investigator | Deep research with YouTube video timestamps |

| Agent | Persona | What They Do | |-------|---------|--------------| | Sorkin | Scriptwriter | Word-count matched scripts with hooks | | Spielberg | Director | Visual directions with source links | | Canvas | Thumbnail Designer | Click-worthy thumbnail AI prompts | | Ranker | SEO Expert | YouTube-optimized metadata |

| Agent | Persona | What They Do | |-------|---------|--------------| | Hunter | Scavenger | URL verification, timestamp extraction | | Vault | Archivist | Downloads clips, screenshots, transcripts | | Chief | Editor-in-Chief | 10-phase deep audit, catches every mistake |

📁 Output Structure

my-documentary/
├── 📋 topic_brief.md        # Topic and angle
├── 📝 truth_dossier.md      # Research with sources
├── ✍️ voice_script.md       # Narration script
├── 🎬 master_script.md      # Script + Visuals
├── 📦 asset_manifest.md     # All asset URLs
├── 📂 assets/               # Downloaded files
│   ├── 001_clip.mp4
│   ├── 002_chart.png
│   └── ...
└── ✅ review_report.md      # Final review

🔧 Configuration

Edit config.yaml to customize:

target_duration: 30          # Minutes
video_format: "investigative" # investigative, explainer, documentary
audio_language: "English"
country: "India"
industry_tag: "political"    # political, finance, crime, tech

🌟 Why VideoNut?

| Feature | VideoNut | Manual Process | |---------|----------|----------------| | Research Time | ~30 mins | 8+ hours | | Script Writing | Auto-generated | Manual | | Asset Finding | Verified URLs | Hunt & Hope | | Downloads | One-click | Individual | | Quality Check | 10-phase audit | Self-review |

🤝 Contributing

We welcome contributions! Check out our Contributing Guide.

Areas We Need Help:

• 🌐 Translations - Agents in other languages
• 🎨 UI Dashboard - Web interface for non-CLI users
• 🔌 Integrations - Video editing software plugins
• 📊 Analytics - Usage tracking and reporting

📖 Documentation

• 📘 User Guide
• 🔄 Agent Lifecycle
• 🔍 Audit Report

📝 License

MIT License - Free for personal and commercial use.

👨‍💻 Author

Vamshi Krishna Konda

⭐ Star this repo if VideoNut helps you create better content!

📦 npm • 💻 GitHub • 🐛 Issues