Skip to main content

​
Quickstart Guide

Get OpenShorts up and running in under 5 minutes using Docker Compose. This guide will walk you through the complete setup from installation to generating your first viral clip.

​
Prerequisites

Before you begin, make sure you have:

Docker & Docker Compose

Required for running OpenShorts containers

Google Gemini API Key

Free API key for AI-powered viral moment detection
Don’t have a Gemini API key? Get one for free at Google AI Studio

​
Installation Steps

1

Clone the Repository

Clone the OpenShorts repository to your local machine:
git clone https://github.com/mutonby/openshorts.git
cd openshorts
2

Launch with Docker Compose

Build and start all services with a single command:
docker compose up --build
This will:
  • Build the backend container (FastAPI + Python AI processing)
  • Build the frontend container (React dashboard with Vite)
  • Start both services with automatic restart enabled
  • Map ports: backend on 8000, frontend on 5175
First build may take 2-5 minutes to download dependencies and models. Subsequent starts are much faster.
3

Access the Dashboard

Open your browser and navigate to:
http://localhost:5173
Note: The frontend runs on port 5173 internally, but Docker maps it to 5175 externally. Always use localhost:5173 when accessing from your browser.
4

Configure API Keys

On first launch, you’ll be prompted to enter your API keys:Required:
  • Gemini API Key: For AI-powered viral moment detection and title generation
Optional:
  • Upload-Post API Key: For direct social media posting (free tier available)
  • ElevenLabs API Key: For AI voice dubbing in 30+ languages
API keys are stored encrypted in your browser’s local storage and never sent to any server except the respective API providers.

​
Generate Your First Clip

Now that OpenShorts is running, let’s create your first viral vertical video:
1

Choose Your Source

You can either:
  • Paste a YouTube URL (e.g., a podcast, interview, or tutorial)
  • Upload a local video file (up to 2GB)
# Example YouTube URLs that work great:
https://www.youtube.com/watch?v=xlyjD1qCaX0  # Interviews
https://www.youtube.com/watch?v=...           # Podcasts
https://www.youtube.com/watch?v=...           # Tutorials
2

Click Generate Clips

Hit the “Generate Clips” button and watch the magic happen!The dashboard will show real-time progress:
  • Video download/upload progress
  • Transcription status
  • AI analysis of viral moments
  • Clip extraction and processing
  • Vertical reframing with subject tracking
Processing time varies by video length. A 10-minute video typically takes 2-4 minutes to process and generate 3-15 clips.
3

Review Generated Clips

Once processing completes, you’ll see:
  • All generated clips in the results feed
  • AI-generated titles and descriptions for each clip
  • Preview thumbnails
  • Download options
Each clip is automatically:
  • Cropped to 9:16 vertical format
  • Stabilized with “Heavy Tripod” smoothing
  • Optimized for TikTok, Instagram Reels, and YouTube Shorts
4

Download or Post

For each clip, you can:Download: Save the MP4 file to your devicePost to Social Media (if Upload-Post API key configured):
  • Select your social profile
  • Choose platforms: TikTok, Instagram, YouTube
  • Customize title and description
  • Post with a single click
Apply Effects (optional):
  • Add AI-generated subtitles
  • Apply text hook overlays
  • Dub to another language with voice cloning

​
Example Workflow

Here’s a complete example processing a YouTube video: 
# 1. Start OpenShorts
docker compose up --build

# 2. Open browser
open http://localhost:5173
Dashboard Process:
  1. Paste YouTube URL: https://www.youtube.com/watch?v=xlyjD1qCaX0
  2. Enter Gemini API key in settings
  3. Click “Generate Clips”
  4. Wait 2-4 minutes for processing
  5. Download or post your 3-15 viral clips

​
Optional Enhancements

​
Enable Social Media Posting

To post clips directly to social platforms:
1

Sign Up for Upload-Post

  1. Visit app.upload-post.com/login
  2. Create a free account (no credit card required)
2

Connect Social Accounts

  1. Go to Manage Users
  2. Create a user profile
  3. Connect your TikTok, Instagram, or YouTube accounts
3

Get API Key

  1. Navigate to API Keys
  2. Generate your API key
  3. Paste it in OpenShorts dashboard settings

​
Enable AI Voice Dubbing

To translate clips to 30+ languages:
  1. Sign up at elevenlabs.io
  2. Get your API key from the dashboard
  3. Enter it in OpenShorts settings
  4. Use the “Translate” button on any generated clip

​
Enable S3 Backup

To automatically backup clips to AWS S3, see the Installation Guide or AWS S3 Backup Guide.

​
Next Steps

Installation Guide

Detailed environment setup and configuration options

API Reference

Integrate OpenShorts into your own applications

YouTube Studio

Learn about AI title and thumbnail generation

Troubleshooting

Common issues and solutions

​
Need Help?

Join the Community

Report issues, request features, or get help from the community

Build docs developers (and LLMs) love

Get started for freeTalk to us