OS OpenShorts GitHub

Open source · MIT · self-hosted

OpenShorts on GitHub, with the install steps the README buries

The openshorts GitHub repo is the open-source OpusClip alternative: it cuts long videos into 9:16 shorts with AI moment detection, face tracking and burned-in captions. This is the field manual for running it yourself — install, keys, GPU, and the problems that actually come up.

License
MIT
Minimum RAM
8 GB+
On CPU
5–8 min per 8-min video
On NVIDIA GPU
About 50 seconds

Quick start

From clone to first clip

  1. 01
    git clone https://github.com/mutonby/openshorts.git
    cd openshorts

    The upstream repo behind openshorts.app. MIT licensed, so cloning costs nothing.

  2. 02
    cp .env.example .env

    Optional. Everything in .env.example has a working default except your own API keys and the optional S3 backup.

  3. 03
    docker compose up --build

    Brings up three containers: the API, the dashboard you use, and the Remotion render service.

  4. 04
    open http://localhost:5175

    The dashboard. Paste a YouTube link or upload a file, then pick from the moments it scores. Port mappings and what each service answers on are in the install guide.

Want the long version, GPU flags and a box with no Google key? Read the full install guide.

What is in the repo

Three tools, one Docker stack

Clip Generator

A link or an upload in, reframed and captioned 9:16 clips out, with a hook line and a virality score.

AI Shorts (UGC)

Marketing clips with AI actors and lip-sync, built from a product URL or a description.

YouTube Studio

Titles, thumbnails and descriptions for the channel you already have, plus one-click publish.

Autopilot (cloud only)

Clips every new upload on its own. Not part of the self-hosted stack.

What OpenShorts actually is

The openshorts GitHub repo — mutonby/openshorts — is an open-source AI clip generator: give it a long video, a podcast, a webinar, a stream, an interview, and it returns finished vertical clips. Three things happen between those two points, and knowing them explains most of the settings you will touch later:

  • Moment detection. Google Gemini 3.1 Flash-Lite ranks the transcript and the scene boundaries, then picks 3 to 15 moments of 15 to 60 seconds each, with a virality score attached.
  • Reframing. For every scene it chooses a layout: TRACK follows a face with MediaPipe and YOLOv8, GENERAL keeps the wide shot over a blurred background, SPLIT stacks two speakers and puts captions on the seam between them, and SCREENCAST places the screen above the presenter.
  • Captions and finishing. faster-whisper (or Parakeet on GPU) transcribes with word-level timestamps, the captions are burned into the frame, an opening hook line is written from what is said, and ElevenLabs can dub the result into 30+ languages if you bring a key.

The same repository also carries two side tools, AI Shorts (UGC marketing videos with AI actors) and YouTube Studio (titles, thumbnails, descriptions, one-click publish), plus an /mcp endpoint and a REST API with keys for whatever agent or n8n flow you want to wire into it. The four commands above are all it takes to see it running.

Do I have to install it, or can I use it online?

No installation is required to use OpenShorts. Docker is the price of running it yourself, not the price of using it. Two hosted sites run the same software and they are not the same operation:

  • openshorts.app — the hosted build made from this repo, and the cloud link the upstream README itself points to. Free plan: your first video is clipped whole up to 60 minutes, then 20 minutes a month, exports carry a watermark, and no card is asked for. Paid plans start at $12/month for 100 minutes.
  • openshorts.io — an independent deployment of the same MIT code, with separate accounts, separate plans and its own 15-minute monthly free tier. It is not operated by openshorts.app, and the upstream README points at openshorts.app, not at it.

Either hosted route needs a free account. Self-hosting needs no account at all: you own the machine, the keys and the files. If you are weighing the two, the self-hosted vs cloud page runs the break-even.

What happens after the four steps

The first thing you see is not a finished clip. docker compose up --build ends with three containers running — the API on 8000, the dashboard on 5175, the render service on 3100 — and the work then happens in stages you can watch:

  • The link is downloaded, not streamed. Paste a YouTube URL and yt-dlp pulls the file onto your own disk first. This is also the stage that fails most often: private videos, age-gated videos and bot checks on a datacenter IP all stop here, and YOUTUBE_COOKIES is the escape hatch.
  • The quality gate runs before the work does. A YouTube source below 720p gets a warning before anything is transcribed, because a 360p frame scaled to 1080x1920 has no pixels to spare. Files you upload directly skip the gate.
  • Transcription first, scoring second. faster-whisper writes word-level timestamps, then the moment picker scores the transcript and returns 3 to 15 candidates of 15 to 60 seconds. Five jobs can run at once by default (MAX_CONCURRENT_JOBS); raise it on a GPU box only as far as the VRAM allows.
  • Clips land in ./output. One MP4 per clip, in a folder the stack never tidies for you. The dashboard shows the same clips, so treat ./output as the copy you own and the folder to watch for disk growth.
  • The job record is temporary, the files are not. A finished job is cleaned out of the queue an hour after it finishes; the MP4s in ./output stay until you delete them.

Three of those stages can send something to a model provider, and exactly what each one sends — transcript, sampled frames, or in two cases the whole source file — is set out on the self-hosted privacy page.

For a first run, pick a source you can afford to lose and keep it to ten or twenty minutes of talking head. On CPU that is a background job at the README's rate — roughly 5 to 8 minutes of processing per 8 minutes of source — and a short source makes a bad setting obvious in one cup of coffee instead of an afternoon. The YouTube to Shorts walkthrough goes through the same pipeline stage by stage, with the variables that change each one.

Where to start depends on what you need

Most people arrive here in one of four states, and each has its own page. You read about the repo somewhere and want to know what running it actually takes: start with install. You want OpusClip's output without a monthly bill and need to know whether that is realistic on a laptop: read self-hosted vs cloud. Or you already cloned it and are stuck on a key, a port or a render that never finishes: go straight to troubleshooting. And if you have not decided whether to install anything at all, the section above is the whole decision: hosted is a signup, self-hosted is an evening.

Does self-hosting really stay free?

The repository is MIT licensed, and the self-hosted build has no watermark and no upload cap. What it costs you is a machine, your own Gemini / ElevenLabs / fal.ai keys, and the time to keep it running. On CPU, budget 5 to 8 minutes of processing per 8 minutes of source video; with an NVIDIA GPU the README quotes about 50 seconds.

Against the hosted clip tools, the entry tiers all land within a few dollars of each other and none of them are open source, so the real question is volume and privacy rather than sticker price. The alternatives page has the current table with each vendor's own pricing page linked, and the self-hosted vs cloud page runs the break-even on the project's own two paths.

"No limits, ever" is about billing — these defaults still ship switched on

The README's no-cap line is true as written: no watermark, no minute counter, no cap on how many videos you process. What it does not describe is the configuration that arrives switched on in .env.example, and that is what people hit on day two:

  • Per-IP rate limits. Processing is limited to 60 requests an hour, MCP to 240 a minute, sign-in to 30 per 10 minutes. Behind your own firewall the whole thing goes off with RATE_LIMIT_ENABLED=0.
  • One GPU transcription at a time. ASR_GPU_CONCURRENCY defaults to 1, and the file's own note says to keep it at 1 unless the GPU has VRAM to spare.
  • A quality gate on YouTube sources. Anything below 720p gets a warning before processing starts; QUALITY_GATE_MIN_HEIGHT=0 turns the gate off.
  • A ceiling on the paid download proxy. Once PAID_PROXY_DAILY_MB (500 MB by default) is spent, the proxy drops out of every chain until midnight UTC, and the jobs that needed it fail with a clear error instead of hanging.
  • Your uptime is the only real limit. The /mcp endpoint runs the same code as the cloud one, but only while your machine is on. Autopilot is not in the self-hosted stack, and auto-posting needs your own Upload-Post account and key.

None of that is a subscription cap and none of it costs money. It is the gap between "no limits" and "no limits until a default gets in your way", and every item on the list is one environment variable.

Several repositories share this name

Search for the name and you will find more than one repo with a nearly identical description. The upstream one — the codebase behind openshorts.app, and the one this site documents — is mutonby/openshorts. Others (quatrixone/openshorts, jnMetaCode/openshorts) reuse the name with different owners and scope, and INAPP-Mobile/openshorts-fresh is a Railway template for it. If a tutorial's screenshots do not match yours, check which repo you cloned before you debug anything else. The same confusion happens one level up, between the two hosted sites: the second section above sorts that one out.

Questions

OpenShorts GitHub FAQ

Is OpenShorts really free?

Self-hosted: yes. MIT license, no watermark, no upload cap, no per-minute billing — the only costs are your machine and your own API keys. The defaults that do exist on a self-hosted box (rate limits, one GPU transcription at a time) cost nothing and are all environment variables; they are listed in the billing section above. The hosted cloud is a separate product with its own free tier and paid plans; the self-hosted vs cloud page on this site compares the two, free tier included.

Can I use OpenShorts without installing Docker?

Yes, if you use a hosted deployment — Docker is only needed to self-host. openshorts.app is the hosted build the repository's own README points to: free plan clips your first video whole up to 60 minutes and then 20 minutes a month, exports carry a watermark, and no card is required; paid plans start at $12/month for 100 minutes. openshorts.io is a separate deployment of the same MIT code with its own 15-minute monthly free tier. Both require an account; self-hosting requires none.

If I self-host, do my videos leave my machine?

No OpenShorts server is in the loop — there is none on the self-hosted path, and the files stay where you put them. What can still leave the machine is whatever the optional AI stages call: Gemini receives the transcript, plus the frames it samples for scene and layout decisions (the full source video too, on the layout and silent-video stages); ElevenLabs receives audio only if you switch on dubbing; the AI Shorts image model gets the actor photo only if you use that tool. Point LLM_BASE_URL at Ollama, LM Studio, vLLM or any OpenAI-compatible server and the moment picker runs on your own model with no Google key; the frame-based stages still call Gemini unless you leave those features off. The API keys page walks through the no-Google setup.

Which site is the real one: openshorts.app or openshorts.io?

openshorts.app is the hosted version built from this repo, and the cloud link in the upstream README points there. openshorts.io is an independent deployment of the same MIT code: separate accounts, separate plans, separate prices, not operated by openshorts.app. This site is independent of both — it documents the upstream repo mutonby/openshorts.

Do I need a GPU to run it?

No. On CPU the README quotes 5 to 8 minutes of processing for an 8-minute video, which is fine for occasional use. An NVIDIA GPU brings that to roughly 50 seconds and unlocks NVENC encoding and the Parakeet transcription backend.

Are there other repos called OpenShorts?

Yes, and they are easy to confuse. mutonby/openshorts is the upstream that openshorts.app is built from; quatrixone/openshorts and jnMetaCode/openshorts carry the same name with different owners and scope, and INAPP-Mobile/openshorts-fresh is a Railway template. This site documents the upstream repo only.

What hardware does it need?

Docker, 8 GB of RAM or more, and disk space for the model downloads on first run (Whisper or Parakeet plus the face-tracking models). Everything else — S3-compatible backup storage, GPU rendering, cloud auth — is optional and off by default.

Keep going