Skip to content

YashRohan01/YouTube-BrainRot

BranchesTags

Repository files navigation

🧠 BrainRot - Automated YouTube Shorts Generator

A sophisticated, end-to-end pipeline for generating engaging YouTube Shorts videos from text stories. This project automates the entire workflow from story summarization through final video production, leveraging AI and advanced multimedia processing.

🎯 Project Overview

BrainRot transforms text-based stories into polished YouTube Shorts-optimized videos with:

  • Intelligent story summarization using Google's Gemini AI
  • Dynamic script generation with engaging narration
  • High-quality text-to-speech voice synthesis (Edge-TTS)
  • Automatic subtitle generation with speech-to-text (Faster-Whisper)
  • Professional video composition with background integration
  • Metadata generation (titles, hashtags, descriptions)

Target Format: Vertical videos (1080×1920) optimized for YouTube Shorts (55-85 seconds)

📁 Project Structure

BrainRot/
├── main.py                 # 🔴 Primary orchestration pipeline
├── summarizer.py           # AI-powered story summarization
├── script_generator.py      # Dynamic narration script generation
├── voice_generator.py       # Text-to-speech voice synthesis
├── subtitles.py            # Automatic subtitle generation
├── video_ffmpeg.py         # Video composition & encoding
├── video_maker.py          # Alternative video generation (MoviePy)
├── models.py               # Pydantic data models
├── trial.py                # Voice testing utility
├── main_1.py               # Alternative TTS pipeline (archived)
├── backgrounds/
│   └── minecraft.mp4       # Sample background video
├── Input Stories/          # Source story files
│   └── Humble Pi/
│       ├── Chapter 1/
│       │   ├── 1-1.txt through 1-5.txt
│       │   └── ...
│       └── Chapter 2/
│           └── *.txt files
└── output/                 # Generated video outputs
    └── [Video Title]/
        ├── voice.mp3
        ├── subtitles.ass
        ├── [title].mp4
        ├── hashtags.txt
        └── description.txt

🚀 Core Components

1. summarizer.py - Story Summarization

Uses Google's Gemini 2.5 Flash model to intelligently summarize input stories.

Key Features:

  • Removes personal author information
  • Preserves all proper nouns and scientific facts
  • Retains engaging human expressions
  • Optimizes for YouTube Shorts narration

Usage:

from summarizer import summarize_story

summary = summarize_story("./Input Stories/path/to/story.txt")

2. script_generator.py - Script Generation

Converts summaries into fast-paced, scientifically accurate narration scripts.

Output Structure (Pydantic Model):

  • script_text: 55-85 second narration
  • script_title: Catchy video title
  • hashtags: 5-10 relevant hashtags
  • description: YouTube Shorts description

Generation Rules:

  • Opens with the scientific/mathematical concept
  • Uses conversational, light-hearted tone
  • Includes clear causality explanation
  • Avoids filler and exaggeration
  • No special symbols or formatting

Usage:

from script_generator import generate_script

script_text, title, hashtags, description = generate_script(summary)

3. voice_generator.py - Text-to-Speech

Generates natural-sounding narration using Microsoft Edge-TTS.

Features:

  • Random voice selection (Ryan or Sonia)
  • Configurable speed multiplier (default: 1.15x for Shorts pacing)
  • Async TTS generation
  • Optional speed enhancement via FFmpeg
  • Output: MP3 format

Available Voices:

  • en-GB-RyanNeural (Male)
  • en-GB-SoniaNeural (Female)

Usage:

from voice_generator import generate_voice

voice_path = generate_voice(script_text, "output/voice.mp3", speed_multiplier=1.15)

4. subtitles.py - Subtitle Generation

Generates ASS-format subtitles using OpenAI's Faster-Whisper model.

Features:

  • Word-level timestamp accuracy
  • Yellow-to-white highlight animation
  • ASS format (compatible with FFmpeg subtitle filter)
  • Optimized for vertical video (1080×1920)
  • CPU-based inference (INT8 quantization)

Output Format:

  • Each word receives individual timing
  • Karaoke-style highlighting effect
  • ASS metadata optimized for Shorts

Usage:

from subtitles import generate_subtitles

subs_path = generate_subtitles("voice.mp3", "output/subtitles.ass")

5. video_ffmpeg.py - Video Composition

Produces the final video using FFmpeg with advanced filtering.

Features:

  • Vertical crop optimization (9:16 aspect ratio)
  • Intelligent background timing (random offset within duration)
  • Audio-video synchronization
  • Subtitle embedding
  • H.264 video codec (high profile, level 4.2)
  • AAC audio codec (192k bitrate)

Processing Pipeline:

  1. Random background offset calculation
  2. Vertical crop filter (9:16 aspect ratio)
  3. Scale to 1080×1920
  4. Subtitle overlay
  5. Audio sync to narration duration
  6. Encoding to H.264/AAC

Usage:

from video_ffmpeg import make_video_ffmpeg

output = make_video_ffmpeg(
    background="./backgrounds/minecraft.mp4",
    audio="voice.mp3",
    subtitles="subtitles.ass",
    output="output/final_video.mp4"
)

6. models.py - Data Models

Pydantic models ensuring type safety and validation.

Models:

  • Summarizer: Summary output validation
  • Script: Structured script generation output

7. main.py - Main Pipeline Orchestrator 🔴

The complete end-to-end pipeline connecting all components.

Workflow:

  1. Read input story file
  2. Summarize using Gemini
  3. Generate script with metadata
  4. Create output directory structure
  5. Generate voice narration
  6. Generate subtitles
  7. Compose final video
  8. Save hashtags and description
  9. Clean up temporary files

Key Features:

  • Filename sanitization for cross-platform compatibility
  • Organized output directory per video
  • Automatic directory creation
  • Temporary subtitle handling for FFmpeg compatibility
  • Comprehensive progress logging

Usage:

python main.py

🛠️ Installation & Setup

Prerequisites

  • Python 3.10+
  • FFmpeg and FFprobe (for video processing)
  • Edge-TTS support libraries

Step 1: Clone and Install Dependencies

pip install -r requirements.txt

Key Dependencies:

langchain
langchain-google-genai
google-generativeai
edge-tts
faster-whisper
moviepy
pydantic
python-dotenv

Step 2: Configure API Keys

Create a .env file in the project root:

GEMINI_API_KEY=your_google_gemini_api_key_here

Step 3: Verify FFmpeg Installation

ffmpeg -version
ffprobe -version

Step 4: Prepare Input Stories

Place story files in:

./Input Stories/[Book Name]/[Chapter]/[Story].txt

Example:

./Input Stories/Humble Pi/Chapter 2/2.txt

🎬 Usage

Quick Start

  1. Update the input story path in main.py:
story_path = "./Input Stories/Humble Pi/Chapter 2/2.txt"

  1. Ensure a background video exists in ./backgrounds/

  2. Run the pipeline:

python main.py

Output Structure

After running, you'll find generated content in ./output/[Video Title]/:

output/
└── The Wobbly Bridge When Physics Shook London/
    ├── voice.mp3              # Generated narration
    ├── subtitles.ass          # SRT-format subtitles
    ├── [title].mp4            # Final video
    ├── hashtags.txt           # Social media hashtags
    └── description.txt        # YouTube description

Customization

Change Voice: Edit voice_generator.py:

VOICES = [
    "en-GB-RyanNeural",    # Male
    "en-GB-SoniaNeural"    # Female
    # Add more voices as needed
]

Adjust Narration Speed:

generate_voice(script_text, "voice.mp3", speed_multiplier=1.2)

Modify Video Resolution: In video_ffmpeg.py, adjust the scale filter:

vf_filter = "crop=ih*9/16:ih:(iw-ih*9/16)/2:0,scale=1920:3040,..."  # 2K Shorts

Change Background Video:

make_video_ffmpeg(
    background="./backgrounds/your_video.mp4",
    ...
)

📊 Processing Pipeline Diagram

Input Story
    ↓
[Summarizer] → Summarize with Gemini
    ↓
[Script Generator] → Create narration + metadata
    ↓
[Voice Generator] → TTS with Edge-TTS
    ↓
[Subtitle Generator] → Whisper transcription
    ↓
[Video Composer] → FFmpeg rendering
    ↓
Final Video + Metadata

🧪 Testing & Utilities

Voice Testing (trial.py)

Test different TTS voices interactively:

python trial.py

This utility:

  • Cycles through available voices
  • Plays each voice sample
  • Allows manual selection
  • Useful for audio quality testing

⚙️ Configuration & Performance Tips

Faster Processing

  • Whisper Model: Use "tiny" instead of "base" for speed (lower accuracy)
  • Video Encoding: Change preset from "fast" to "ultrafast" (lower quality)
  • FFmpeg Concurrency: Set threads appropriately for your CPU

Better Quality

  • Whisper Model: Use "small" or "medium" (slower)
  • Video Encoding: Use "slow" preset (takes longer)
  • Voice Speed: Lower SPEED_MULTIPLIER for clearer speech

Memory Optimization

  • Process videos in batches with separate background videos
  • Use CPU mode for Whisper on limited VRAM systems
  • Consider streaming background video clips

🔧 Troubleshooting

Issue: "ffmpeg not found"

Solution: Install FFmpeg from https://ffmpeg.org/download.html and add to PATH

Issue: Subtitle positioning incorrect

Solution: Verify video dimensions in video_ffmpeg.py:

scale=1080:1920  # Must match output resolution

Issue: Voice sounds robotic

Solution: Reduce speed multiplier or try different voices in VOICES list

Issue: Missing Gemini API key

Solution: Ensure .env file exists with valid GEMINI_API_KEY

Issue: Video processing slow

Solution:

  • Reduce FFmpeg preset to "ultrafast"
  • Use Whisper "tiny" model
  • Process in parallel with multiple instances

📝 File Details

File Purpose Language
main.py Main orchestration pipeline Python
summarizer.py Gemini-powered summarization Python
script_generator.py Dynamic script generation Python
voice_generator.py Edge-TTS integration Python
subtitles.py Whisper subtitle generation Python
video_ffmpeg.py FFmpeg video composition Python
models.py Pydantic validation models Python

🚦 Dependencies Reference

Package Purpose Version
langchain LLM framework Latest
google-generativeai Gemini API client Latest
edge-tts Microsoft TTS Latest
faster-whisper OpenAI speech recognition Latest
moviepy Video processing (alternative) Latest
pydantic Data validation v2+
ffmpeg Video encoding (system) 4.4+

🎬 Output Examples

The pipeline generates:

Video File: MP4 (H.264/AAC)

  • Resolution: 1080×1920 (9:16 vertical)
  • Duration: 55-85 seconds
  • Bitrate: Optimized for streaming

Metadata Files:

  • hashtags.txt: Social media ready
  • description.txt: YouTube Shorts optimized
  • subtitles.ass: Professional formatting

🤝 Contributing

To extend this project:

  1. Add new story sources to Input Stories/
  2. Modify script generation prompts in script_generator.py
  3. Add background videos to backgrounds/
  4. Customize models in models.py

⚖️ License

This project uses:

  • Google Gemini API
  • Microsoft Edge-TTS
  • OpenAI Faster-Whisper
  • FFmpeg (LGPL)

📧 Support

For issues with:

  • Video processing: Check FFmpeg installation
  • API errors: Verify Gemini API key in .env
  • Voice quality: Adjust speed multiplier and voice selection
  • Subtitles: Check Whisper model compatibility

🔮 Future Enhancements

  • Batch processing multiple stories
  • Custom background video management
  • Dynamic thumbnail generation
  • Multi-language support
  • Alternative LLM integration (Claude, GPT-4)
  • Web UI dashboard
  • Scheduled uploads
  • Analytics tracking

Created: December 2025
Version: 1.0
Status: Production Ready 🚀

About

Automated YouTube videos hopefully for passive income

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages