⚡ ShortsFlow AI Studio

The self-hosted Opus Clip alternative.
Paste a podcast or YouTube link, get captioned 9:16 Shorts that cut to whoever is talking. Free, local, no watermark, no credit caps.

Clip long videos with local Whisper, an LLM that scores the hooks, face-tracked 9:16 crops, a stacked two-speaker split or active-speaker switching, and Remotion spring captions. Or generate from an idea with 30+ formats (facts quizzes, explainers, top-5 lists, stories) and drive everything from a browser UI, the CLI, Docker, Colab or an MCP agent.

🎬 Running in production: the YouTube channel @spottheliee is generated and posted entirely by ShortsFlow - 6 "spot the lie" Shorts a day from one GitHub Actions workflow.

⭐ If ShortsFlow saves you an Opus Clip subscription, please star the repo - it helps more creators find it.

⚡ Quick Start - pick one

Option	Command	Best for
☁️ Google Colab (free GPU, zero install)		Trying it in 5 minutes
🐳 Docker (browser WebUI)	docker run -p 7860:7860 -e GEMINI_API_KEY=your_key ghcr.io/ghost1412/shorts-generator → open http://localhost:7860	Servers, Linux, no Python setup
📦 pip	pip install "shortsflow @ git+https://github.com/ghost1412/shorts-generator" then shortsflow init and shortsflow doctor	Using it as a command from anywhere
🌐 Browser WebUI	pip install -r requirements-full.txt && python webui.py	Local use with a GPU
🖥️ Desktop Studio GUI (Windows)	setup.bat && launch.bat	Windows desktop
🤖 AI agents	python mcp_server.py or point your agent at SKILL.md	Claude Code, Cursor, n8n

git clone --depth 1 https://github.com/ghost1412/shorts-generator.git
cd shorts-generator

🐧 Linux / macOS: chmod +x setup.sh && ./setup.sh && python3 webui.py

⚡ ShortsFlow vs Opus Clip, Klap & Vizard

Honest take: the paid tools have a nicer editor and scheduling. ShortsFlow wins on cost, privacy, and being scriptable.

🖥️ Desktop Studio GUI (gui_app.py)

• 3-Column Single-Window Studio Layout: Live 9:16 vertical canvas preview, mode picker, preset cards, and 1-click render launcher.
• Interactive Remotion Presets: 1-click selection between HORMOZI, GLOW_BOX, BOUNCE, and MINIMAL spring captions.

🎬 Video Generator Modes

🎛️ Engine Power Capabilities

🎨 Visual Color Grading Presets (--video_filter)

🤖 Model Context Protocol (MCP) & AI Agent Server

ShortsFlow AI Studio provides a native MCP Server (mcp_server.py) allowing AI assistants (Claude Desktop, Cursor, Antigravity, n8n, AutoGPT) to create shorts autonomously:

# Launch MCP Server over standard I/O for AI IDEs & Workflow Engines
python mcp_server.py

Available MCP Tools:

• generate_short: Create AI shorts from topics or prompts.
• extract_clips: Slice long YouTube videos into vertical shorts with face tracking, a stacked two-speaker split (layout: split) or active-speaker switching (layout: active).
• generate_social_package: Generate platform metadata (.meta.json) for YouTube Shorts, TikTok, and Reels.
• get_render_status: Query live rendering job progress.

🔌 REST API & Webhooks

pip install -r requirements-full.txt
SHORTSFLOW_API_KEY=change-me python -m shortsflow.api        # http://127.0.0.1:8080/docs

curl -X POST localhost:8080/v1/clips -H "Authorization: Bearer change-me" -H "Content-Type: application/json"   -d '{"source_video": "https://youtu.be/VIDEO_ID", "layout": "active", "clip_count": 3, "webhook_url": "https://example.com/hook"}'
# -> {"id": "a1b2c3", "status": "queued", "url": "/v1/jobs/a1b2c3"}
curl localhost:8080/v1/jobs/a1b2c3 -H "Authorization: Bearer change-me"   # status + files[] download links

POST /v1/shorts generates from an idea (mode, category, prompt...). Webhooks are signed with X-ShortsFlow-Signature: sha256=<HMAC of body> when SHORTSFLOW_WEBHOOK_SECRET is set. Jobs run one at a time by default (SHORTSFLOW_MAX_CONCURRENT). With Docker: SHORTSFLOW_API_KEY=change-me docker compose --profile api up api (refuses to start without a key). A ready-made n8n flow lives in examples/n8n/.

📤 Publish & Schedule (TikTok, Instagram Reels, YouTube Shorts)

Clip extraction writes metadata.json (title, description, tags) and a badge thumbnail next to every clip. Post them with Upload-Post, which holds the platform logins (set UPLOAD_POST_API_KEY and UPLOAD_POST_USER):

# preview what would be posted, then post now or stagger one clip every 3 hours
python -m engine.publish sessions/extraction_123/metadata.json --platforms tiktok,instagram,youtube --dry-run
python -m engine.publish sessions/extraction_123/metadata.json --platforms tiktok,instagram --start 2026-11-02T10:00 --every 180 --timezone Europe/Madrid

🏷️ Brand Kit

Burn your logo, @handle and a closing end card into every clip (placed clear of the Shorts/Reels UI):

py main.py --source_video "URL" --logo logo.png --handle @mychannel --end_card "Follow for more"
py main.py --source_video "URL" --brand examples/brand.json      # same thing as a preset file
python -m engine.branding existing_clip.mp4 --logo logo.png --handle @mychannel   # any finished video

💡 Top Command Recipes

# 1. Podcast Shorts that cut to whoever is talking (stacked split when unsure) + silence removal
py main.py --source_video "https://www.youtube.com/watch?v=VIDEO_ID" --extract_mode shorts --layout active --tighten --use_remotion

# 1b. Prompt-based clipping: only the moments that match your request (LLM search, keyword fallback offline)
py main.py --source_video "https://www.youtube.com/watch?v=VIDEO_ID" --find "where they discuss pricing" --clip_count 3 --use_remotion

# 1a. Cut the ums and uhs (and silences) out of clips
py main.py --source_video "URL" --tighten --remove_fillers --use_remotion

# 1c. Emoji pop on keywords in HORMOZI/BOUNCE captions (needs an emoji font; included in the Docker image)
py main.py --source_video "URL" --use_remotion --caption_style HORMOZI --caption_emoji

# 1d. Fully local, zero-cost voice: Kokoro TTS (no API key; ~120 MB model downloads once)
py main.py --mode FACTS --category "space" --tts_provider kokoro --voice af_heart --use_remotion

# 2. High-Retention Short with Voice Cloning, Zoom Motion & Audio Ducking
py main.py --mode FACTS --category "cyberpunk AI" --tts_provider voicestudio --clone_voice "my_voice.wav" --enable_zoom --auto_ducking --use_remotion

# 3. Render Landscape 16:9 YouTube Video with SFX
py main.py --mode EXPLAINER --prompt "Quantum physics" --aspect_ratio 16:9 --sfx_preset whoosh

# 4. Translate and Dub Video into Spanish
py main.py --mode DUB --source_video "https://www.youtube.com/watch?v=VIDEO_ID" --target_lang es --use_remotion

# 5. Process Batch Content Calendar Queue
py main.py --batch_file "topics.txt" --mode FACTS --aspect_ratio 9:16 --use_remotion

⚙️ Environment Configuration (.env)

Rename env.example to .env:

GEMINI_API_KEY=your_gemini_key_here
HF_API_KEY=your_huggingface_key_here
PEXELS_API_KEY=your_pexels_key_here

# Local Voice Studio & Production Defaults
VOICE_PROVIDER=auto
VOICE_STUDIO_URL=http://localhost:8000/v1/audio/speech
DEFAULT_ASPECT_RATIO=9:16
AUTO_DUCKING=true

🤖 AI Agent Onboarding

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

⭐ Star History

📄 License

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