⚡ 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.

✂️ Clipping demo: the crop follows whoever is talking

The first GIF above is a real run of py main.py --source_video interview.mp4 --layout active --use_remotion on a 4:3, 480p two-person interview: the shot cuts to the speaker, found by voice pitch plus face detection, and Whisper word captions are burned in. Source footage: Aida Thomas Interviews Nancy Many - Part 1 by Aida Thomas, CC BY-SA 3.0; the demo GIF is a derivative and is shared under the same licence.

🎛️ Review, restyle and brand your shorts

After Make my shorts, the browser app (shortsflow webui) shows every short as a card instead of a bare file list:

• Review: a preview player, a strong / good / okay / weak label with the reason, and a title, description and hashtags ready to copy. Remove what you do not want, then Download all as .zip. Earlier runs can be reopened.
• Edit one short: pick another caption style or change its start and end, and only that short is re-rendered (about a minute). Undo puts the previous version back.
• Caption styles come with a preview, and your brand (logo, @handle, end card, accent colour) is saved once and added to every short.

_{Screenshots use sample clips made from the demo GIFs above.}

⚡ Quick Start - pick one

🪟 Windows: one-click install

⬇ Download ShortsFlow-Setup.exe (or see all releases), run it, then open ShortsFlow from your Desktop. A browser page opens where you paste a video link or upload a file and press one button. No Python, Node or API key to install first.

• The installer downloads roughly 2 GB the first time (about 5 GB with an NVIDIA card, because of the GPU libraries; it fetches its own private Python, the speech-recognition components and Node), so it needs an internet connection and a few minutes. It does not need admin rights.
• It is not code-signed yet, so Windows may show a blue "Windows protected your PC" box: click More info, then Run anyway.
• With an NVIDIA graphics card it uses the GPU (fast). Without one it still works on the CPU, but transcribing a long video takes much longer, and the first run also downloads the speech model.
• Uninstall from Windows Settings > Apps. Your videos and settings in %LOCALAPPDATA%\ShortsFlow\workspace are kept.

🚀 Your first shorts in 3 steps (no API key needed)

Clipping a long video into vertical shorts works without any account or API key. A key (or a free local Ollama) only adds AI titles and descriptions, and is needed for the idea-to-video modes.

1. Install (needs Python 3.12): pip install "shortsflow[clip]"
2. Check your setup: shortsflow doctor lists what is ready and what to fix, in plain words.
3. Make shorts from a file or a link: shortsflow clip my_video.mp4 (or shortsflow clip "https://youtube.com/watch?v=..."). Add --count 5 for more clips, --captions for animated captions (needs Node.js, then run shortsflow init once).

Your shorts are saved in a shortsflow folder in your home directory (the command prints the exact path). Stuck? shortsflow doctor tells you the next step, and error messages say how to fix a bad key or a rate limit.

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 then shortsflow init and shortsflow doctor (clipping: pip install "shortsflow[clip]")	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

# 1e. Edit by transcript: cut phrases, or delete words from the transcript text file and re-run
py main.py --source_video "URL" --session_dir sessions/talk --cut "you know" --cut "so basically"
#   -> writes sessions/talk/transcript.txt; delete words/lines in a copy, then:
py main.py --source_video "URL" --session_dir sessions/talk --edit_transcript my_edit.txt

# 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: planned, not implemented yet (--mode DUB / --target_lang are ignored)

# 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.

The optional animated-caption renderer uses Remotion, which has its own source-available licence (free for individuals and small teams; see remotion.dev/license if you are a larger company). Without Node.js/Remotion you still get clips, just without the animated captions.