⚡ ShortsFlow AI Studio

The Open-Source Opus Clip Alternative Turn Long Videos, YouTube Links, or AI Concepts into High-Retention 9:16 Shorts on Autopilot.

---

⚡ ShortsFlow vs Paid SaaS Tools

Feature	⚡ ShortsFlow AI Studio (Open Source)	💳 Opus Clip / Paid SaaS ($20–$50/mo)
Monthly Cost	$0 / 100% Free Forever	$19 – $49 / month
Data Privacy	100% Local GPU / Private	Your videos uploaded to 3rd party cloud
Creation Modes	AI Clipping + Manim Explainers + Facts + Riddles + WYR	Video clipping only
Subtitle Quality	Remotion React Spring Physics (Hormozi, Glow Box, Bounce)	Basic cloud subtitles
Limits & Watermarks	Unlimited Exports & Zero Watermarks	Monthly credit caps & paid watermark removals
AI LLM Flexibility	Google Gemini, Local Ollama (Qwen/Llama), HuggingFace	Locked cloud AI models

⭐ If ShortsFlow saves you $240+/year on video clipping subscriptions, drop a star on the repo to support independent open-source AI!

---

⚡ Quick Start (Get Your First Video in 60 Seconds)

1-Click Automated Setup (Windows)

# ⚡ 1-Click Fast Clone (~16.5 MB)
git clone --depth 1 https://github.com/ghost1412/shorts-generator.git
cd shorts-generator

# Run 1-Click Setup 
setup.bat

# Launch Interactive Studio Launcher
launch.bat

🐧 Linux & macOS Setup

# ⚡ 1-Click Fast Clone (~16.5 MB)
git clone --depth 1 https://github.com/ghost1412/shorts-generator.git
cd shorts-generator

chmod +x setup.sh
./setup.sh

# Launch Desktop GUI Studio
python3 gui_app.py

🐳 Docker Quickstart (Self-Hosted)

docker compose up -d

---

🖥️ Graphical User Interfaces & Usability

ShortsFlow AI Studio features a sleek, single-window 3-column Studio UI:

1. 🖥️ Standalone Desktop GUI Studio (Easiest)

• Launch Command: launch.bat (Option 1) or python gui_app.py
• Usability Features:
  • Single-window studio layout with 9:16 vertical video preview canvas.
  • Interactive clickable cards for Remotion caption spring physics (HORMOZI, GLOW_BOX, BOUNCE, MINIMAL).
  • Source video URL input, custom output directory picker, standalone content modes, and voiceover selectors.
  • Quality pipeline switches (Smart Crop, Auto-Tighten, HQ, SuperRes, SRT Export, B-Roll).
  • Master 1-click render button with animated progress bar and collapsible live log console.

2. 🌐 Next.js 15 Web Dashboard

• Launch Web Frontend: cd web && npm run dev (Access at http://localhost:3000)
• Launch Render Worker: python server.py (Runs on port 5000)
• Usability Features:
  • Modern browser-based web dashboard.
  • Asynchronous background render queueing via Flask worker (server.py).
  • Multi-user authentication & payment integrations (Stripe/LemonSqueezy).

3. ⚡ Interactive CLI & Scriptable Launcher

• Launch Command: launch.bat (Option 2) or python main.py [FLAGS]
• Usability Features:
  • Step-by-step terminal prompts for quick extraction.
  • 100% scriptable flags for headless server deployment, cron jobs, and GitHub Actions autonomous generation.

---

🔥 Key Features

• 🚀 AI Video Extraction & URL Ingestion: Paste any YouTube link, Podcast URL, or local file. ShortsFlow detects viral hooks, energy shifts, and key moments using multimodal AI analysis.
• 🎨 Visual Filters & Color Grading: 12 custom color grades + AI Auto & AI Dynamic multi-scene timeline filtering.
• 🎞️ Standalone Filter Mode (--mode FILTER): Apply color grading filters directly to any video file without cutting or reframing.
• 💬 4 Subtitle Style Presets:
  • HORMOZI: Dynamic word spring pop, black strokes, multi-color neon highlights (#39FF14, #FFEA00, #00E5FF).
  • GLOW_BOX: Glassmorphic gradient pill box around active phrases with neon glow.
  • BOUNCE: Upward jump animation with intense drop-shadow text glow.
  • MINIMAL: Crisp dark translucent box with accent border.
• ⚡ Parallel Remotion Video Engine: High-performance React subtitle rendering with custom multi-worker thread pools (--max_workers 2 or 4).
• 🤖 Multi-LLM Orchestration: Native support for Google Gemini, OpenAI (gpt-4o-mini), DeepSeek (deepseek-chat), Groq (llama-3.3-70b), Anthropic Claude, OpenRouter, Local Ollama (qwen3:8b), and custom OpenAI-compatible endpoints with automatic failover (--llm_provider & --llm_model).
• 🎯 Smart Crop & Anti-Blinking Face Tracking: Intelligent face detection with Exponential Moving Average (EMA) smoothing and velocity clamping to prevent camera jitter.
• ✂️ Padded Silence Removal: Auto-tighten audio gaps with an 80ms safety buffer to ensure zero word truncation or sub-frame flickering.
• 🧮 Standalone Creation Modes:
  • EXPLAINER: Automated educational math & coding animations powered by Manim.
  • FACTS & STORY: AI-scripted facts and narratives with automated background video stitching.
  • FILTER: Direct visual color grading & style application for full long-form videos or shorts.
  • THIS_OR_THAT / WYR: Split-screen comparison challenges.
  • RANK_IT: Tier-list rank reveals.

---

🎨 Visual Color Grading & AI Filter Modes (--video_filter)

ShortsFlow AI Studio includes an AI-driven color grading engine with 3 modes:

Filter Mode	CLI Flag	How It Works	Best Used For
🧠 AI Dynamic	--video_filter dynamic	AI analyzes video timeline & switches filters automatically per scene phase in a single pass.	High-retention edits (Combat ➔ B&W Duel ➔ Sunset Finish)
🤖 AI Auto	--video_filter auto	AI inspects video context & picks the 1 best overall filter (or none if natural colors are best).	Quick 1-click optimization without guessing filter names
🎨 Manual Preset	--video_filter <name>	Force 1 of 12 iconic visual color grades (kurosawa, cyberpunk, teal_orange, etc.).	Specific aesthetic themes & game styles

🎨 12 Curated Visual Presets

Preset Name	Visual Atmosphere	Preset Name	Visual Atmosphere
kurosawa	Black & White high-contrast samurai + grain	anime_vivid	Bright pastel saturation for anime/cartoons
cyberpunk	Neon boosted purples/blues for night racing	matrix_green	Cyberpunk green tint / hacker aesthetic
teal_orange	Blockbuster movie cinematic color balance	sepia_western	Vintage brown sepia tone for historical clips
cinematic_warm	Golden hour warmth for scenery & drama	cold_thriller	Icy blue desaturated shadows for suspense
vibrant_action	Sharp contrast & saturation boost for combat/sports	hdr_pop	High dynamic range pop with deep contrast
vintage_vhs	Analog retro tape scanlines & color shift	moody_dark	Dark fantasy / horror shadow contrast

---

🏗️ Architecture Flow

graph TD
    A[Source Video / YouTube URL / AI Prompt] --> B(Ingestion & Persistent Cache)
    B -->|Whisper + CUDA GPU| C(Multimodal Signal Analysis)
    C --> D[Hooks, Loudness & Face Tracking]
    D --> E(Viral Scoring Engine)
    E --> F{Smart Editing Pipeline}
    F -->|Crop| G[9:16 Vertical Reframing]
    F -->|Tighten| H[Silence Removal + Safety Buffer]
    F -->|Remotion| I[React Subtitle Animation Engine]
    G & H & I --> J[Final High-Retention Short]

Loading

---

💻 CLI Usage Examples

1. AI Dynamic Scene-Level Filter + Parallel Remotion Render

python main.py --source_video "gameplay.mp4" --extract_mode shorts --smart_crop --use_remotion --max_workers 2 --video_filter dynamic --user_context "Samurai katana duel and sunset field"

2. Multi-Provider LLM Override (DeepSeek, OpenAI, Groq, or Local Ollama)

# Use DeepSeek LLM for analysis & scripting
python main.py --source_video "gameplay.mp4" --llm_provider deepseek --llm_model deepseek-chat

# Use Groq for ultra-fast Llama 3.3 70B inference
python main.py --source_video "gameplay.mp4" --llm_provider groq --llm_model llama-3.3-70b-versatile

3. Full Long-Form Video Color Grading Mode (--mode FILTER)

# AI auto-selects visual grade for a long-form video
python main.py --mode FILTER --source_video "night_race.mp4" --video_filter auto

# Manual visual filter preset (e.g. Kurosawa / Cyberpunk / Teal-Orange)
python main.py --mode FILTER --source_video "clip.mp4" --video_filter kurosawa

4. Generate AI Facts Short with Custom Remotion Captions

python main.py --mode FACTS --category "space mysteries" --vibe "suspense" --use_remotion --caption_style GLOW_BOX

4. Generate a Manim Educational Math Explainer Short

python main.py --mode EXPLAINER --prompt "Explain the Pythagorean theorem visually" --extract_mode shorts

---

🎬 Standalone Content Modes

Mode	Format & Visual Style
✂️ AI Video Clipping	Turn YouTube podcasts/long videos into high-retention 9:16 viral shorts
🧮 Explainer (Manim)	Automated math, science, and computer science animations
💡 Facts Mode	High-energy trivia & mystery facts with stock video background loops
📖 Story Mode	AI narrator voiceover with dynamic visual scene stitching
🤔 This or That / WYR	Split-screen dilemma challenge with VS central badge
🏆 Rank It	Sequential Tier List (S, A, B, C, D) item ranking reveal
🧩 Riddle	Interactive lateral thinking challenge designed to drive comments
📰 News & Persona	RSS headline breakdown with optional cartoon personas (e.g. Mafia Cat)

---

⚙️ Prerequisites & Installation

• Python: 3.12+ (PyTorch CUDA recommended for fast Whisper transcription)
• Node.js: v18+ (Required for Remotion React video rendering)
• FFmpeg: Installed and accessible in your system PATH

Environment Configuration (.env)

Create a .env file in the root directory (or run setup.bat):

GEMINI_API_KEY=your_gemini_api_key_here
HF_API_KEY=your_huggingface_key_here
PEXELS_API_KEY=your_pexels_key_here

---

🤖 AI Agent Prompt & Onboarding Instructions

If you are an AI Coding Agent (Cursor, Antigravity, Claude Code, Copilot, AutoGPT) onboarding into this codebase, check out AGENTS.md for structured architectural context, module maps, CLI skills, and execution rules.

---

📄 License

ShortsFlow AI Studio is open-source software licensed under the MIT License.