Vomcat - Automated YouTube Shorts Server

Vomcat is an automated tool designed to analyze long YouTube videos, detect the most viral or engaging moments using Artificial Intelligence (Google Gemini), crop the video to vertical format (Shorts), render dynamic subtitles with highlighted words, progress bars, call-to-actions (CTA), and finally upload them to your YouTube channel on a scheduled sequence.

---

🚀 Key Features

• AI-Powered Viral Detection: Leverages Google Gemini Pro to scan transcripts of video clips and automatically recommend highly engaging timestamps.
• Automated Video Editing: Crops original wide videos to 9:16 vertical ratio, centers the focus, and burns high-performance animated subtitles into the video.
• Style Customization: Choose fonts, sizes, highlight colors, and text presets (shadows, borders, alignments).
• Autopilot Monitoring: Monitors external YouTube channels every 30 minutes, clips new uploads automatically, and drafts/uploads them.
• Scheduled Publishing: Automatically queues uploads and spaces them (e.g., 1.5 hours apart) to avoid YouTube spam triggers and maximize audience reach.
• Engagement Comments: Automatically posts a customized debate question in the comment section of the uploaded Short.

---

⚠️ Troubleshooting & Support

Important

Reporting Failures: If any part of the automatic clipping, transcoding, or monitoring fails, please extract the execution log from the console/logs and send a report to the developer immediately.

Manual Upload Fallback: If the automated YouTube upload fails (due to OAuth token issues, API limits, or connection errors), you can download the rendered Short directly from the local web dashboard gallery and upload it manually via YouTube Studio. Please report the upload error to the developer so the authentication flow can be debugged.

🤖 The yt-dlp Cookie Issue (YouTube Bot Blocking)

YouTube frequently updates its bot detection, which may trigger "confirm you're not a bot" or 403 Forbidden errors during video downloads. This project uses the yt-dlp package, which requires active session cookies to bypass these restrictions.

• Automated Browser Extraction: The server attempts to automatically extract cookies from your active Chrome/Edge profiles on Windows.
• Manual cookies.txt Fallback: If bot blocks persist, download a browser extension (like Get cookies.txt LOCALLY), log into YouTube, export your cookies as a Netscape-format text file, name it cookies.txt, and save it in the root folder of this project.

---

🛠️ Prerequisites

Before running the server, make sure you have:

1. Python 3.8 or superior (Check "Add Python to PATH" during installation).
2. FFmpeg: Required for audio and video transcoding. The dependency imageio-ffmpeg downloads a binary automatically, but a system-wide FFmpeg installation is recommended if codec or performance issues occur.

---

⚙️ Configuration & Environment Variables

The server uses environment variables for third-party authentications.

1. Duplicate the .env.example file and rename it to .env.
2. Configure the following variables:

1. Google Gemini API Key

• Get a free API Key from Google AI Studio.
• Paste it into GEMINI_API_KEY=your_key_here.

2. YouTube OAuth v3 API

To authorize the app to upload directly to your channel:

1. Go to Google Cloud Console.
2. Create a project and enable the YouTube Data API v3.
3. Set up the OAuth Consent Screen (select "External" and add your email as a "Test User").
4. Create credentials for an OAuth Client ID (select "Desktop Application").
5. Copy the credentials to your .env file:
   • YOUTUBE_CLIENT_ID=your_client_id
   • YOUTUBE_CLIENT_SECRET=your_client_secret
   • YOUTUBE_PROJECT_ID=your_project_id

(Alternative: Download the JSON file from Cloud Console, rename it to client_secrets.json and save it directly in the project root).

---

🏃 How to Run

For Windows users, double-click the included batch file:

run.bat

This batch file will:

1. Check if Python is installed.
2. Setup and activate a local virtual environment (venv).
3. Install required packages from requirements.txt.
4. Create a default .env configuration file if missing.
5. Launch the FastAPI server at http://127.0.0.1:8000 and automatically open it in your browser.

---

📁 Repository Structure

• app/main.py: FastAPI server routes, tasks, and background job queue.
• app/downloader.py: Downloads audio and video clips from YouTube using yt-dlp.
• app/analyzer.py: Integrates with Gemini API to detect viral parts.
• app/transcriber.py: Transcribes audio clips using Gemini/YouTube transcripts.
• app/editor.py: Crops video, burns subtitles, adds progress bar and CTA overlay using FFmpeg.
• app/uploader.py: Handles Google OAuth 2.0 and uploads Shorts to YouTube.
• app/monitor.py: The background pilot autopilot loops that monitor external channels.
• app/templates/ & app/static/: Front-end components.