01
Why self-host a clipper at all
Three reasons come up again and again: footage you are not allowed to upload, cost once the volume grows, and wanting to change how the clipper cuts.
- Private footage. The video file is processed on your machine. Client calls, internal meetings and unreleased material never go to a third-party clipping service.
- Cost at volume. Hosted clippers bill per minute of source video (see our hosted pricing for a comparison). A self-hosted clip maker costs what your hardware and model usage cost.
- Control. The code is yours to read and change: prompts, caption style, crop behaviour, encoder settings.
02
What runs in the pipeline
The pipeline has five stages, and all of them run locally except the moment picker, which calls a language model with the transcript text.
| Stage | What it does | Runs with |
|---|---|---|
| Transcription | Speech to text with a timestamp per word | faster-whisper (local) |
| Scene detection | Finds the shot boundaries | TransNetV2 / PySceneDetect (local) |
| Moment picking | Scores transcript windows, returns start, end and title | Gemini, or a local model through LLM_BASE_URL |
| Reframing | Tracks the speaker and crops each shot to 9:16 | YOLOv8 and MediaPipe (local) |
| Captions and encode | Burns word-level captions, writes H.264 MP4 | FFmpeg (local) |
The moment picker sends the transcript, not the video. Features that have to look at frames, such as the automatic layout picker, use Gemini when a key is set.
03
OpenShorts on GitHub: clone, deploy, self-host
The OpenShorts GitHub repository is mutonby/openshorts. Clone it and start the stack:
$ git clone https://github.com/mutonby/openshorts.git$ cd openshorts$ cp .env.example .env$ docker compose up --build# then open http://localhost:5175- The
cpstep is optional. The.envfile holds server settings such as S3 backup; the stack starts without it. - Open the dashboard on port 5175, go to Settings and paste your Gemini API key. Google issues one free in AI Studio.
- In Clip Generator, upload a long video or paste a link, and wait for the clips.
The first build downloads the models and takes a while. Later starts are fast.
04
Check that it works
Three checks confirm the install before you spend time on a long video.
- Containers are up.
docker compose psshould listopenshorts-backend,openshorts-frontendandopenshorts-rendereras running. - Both ports answer. The dashboard is on
http://localhost:5175. The API is on port 8000, with interactive documentation athttp://localhost:8000/docs. - A short test clip finishes. Use a talking video of two or three minutes first. A finished job shows vertical clips with captions in the dashboard; the files are written to the
outputfolder of the repository.
In our run, a 3-minute speech came back as three clips of 25 to 31 seconds, each with a title and word-by-word captions.
05
MCP server and API
OpenShorts ships an MCP server, a REST API and a CLI, so Claude, Cursor or a script can submit a video and collect the clips. On a self-hosted build none of it is metered and no API key is needed. If you would rather not run a server, the hosted OpenShorts MCP server works the same way with a personal API key.
$ claude mcp add --transport http openshorts http://localhost:8000/mcp$ claude mcp add openshorts -- python mcp_stdio.py# first line: over HTTP; second: over stdio, without the web serverThe MCP tools include process_video, create_upload, get_job_status and list_clips. The REST endpoint is POST /api/process; pass a webhook_url to get one call when the job ends instead of polling.
$ pip install openshorts$ export OPENSHORTS_API_URL=http://localhost:8000$ openshorts process "https://youtube.com/watch?v=..." --wait06
Windows and WSL
On Windows, run OpenShorts through Docker Desktop with the WSL2 backend. The project README gives two rules for GPU use: install the NVIDIA driver on Windows itself, and do not install a driver inside WSL.
- Clone the repository inside the WSL filesystem, for example under your Linux home folder. Docker reads files there much faster than from a mounted Windows drive.
- Run the same four commands from the WSL terminal.
- Open
http://localhost:5175in your Windows browser; Docker Desktop forwards the port.
We have not run the Windows path ourselves yet. The steps above are the README's instructions plus standard Docker Desktop practice.
07
Common errors and fixes
| Symptom | Cause | Fix |
|---|---|---|
| A YouTube link fails with "Sign in to confirm you’re not a bot" | YouTube blocks many datacentre IP addresses. We hit this on a cloud server with every player client. | Run it on a home connection, upload the file instead, or route downloads through a residential proxy with PROXY_URL. |
| Clips take many minutes | The default image is CPU-only and video encoding is CPU-heavy. | Expected on CPU. Use the GPU build on an NVIDIA card with NVENC, or start with shorter videos. |
| Local model returns broken or cut-off results | Ollama defaults to a 4,096-token context and truncates silently. | Set OLLAMA_CONTEXT_LENGTH=16384. The README recommends models of 7B parameters or more. |
| A silent video fails | With no speech there is no transcript to pick moments from; this case needs a model that can look at frames. | Add a Gemini API key alongside LLM_BASE_URL. |
| Whisper reports a CUDA error | The GPU ran out of memory. | The job retries once on CPU by itself. Lower ASR_GPU_CONCURRENCY to 1 if it repeats. |
The first row is from our own test. The other rows come from the project README.
08
Hardware and speed, measured
Docker and 8 GB of RAM are the starting point. We measured the CPU path on one machine; treat the numbers as one data point, not a benchmark.
| Job | Output | Time | Peak memory |
|---|---|---|---|
| Reframe one 3:01 source (1080p) to vertical | 1 file, 1080×1920, 3:00 | 10 min 53 s | about 0.85 GB |
| Pick and render 3 clips from the same source, with captions | 3 files, 85 s in total | 13 min 37 s | about 1.1 GB |
- Machine: 4 shared vCPUs, 8 GB RAM, no GPU, x264 encoder. Tested on 15 and 16 November 2026.
- The second job shared the CPU with other work and ran at low priority, so it is slower than an idle machine would be.
- Transcription ran separately in both jobs. The times cover scene detection, tracking, cropping, captions and encoding.
- All four cores stayed busy, so plan for one job at a time on a machine this size.
For GPUs we have no measurement of our own. The README states that an NVIDIA card with NVENC clips an 8-minute video in about a minute, and that 8 GB of VRAM is enough for the large-v3-turbo transcription model plus the detection models.
09
What the licence lets you do
The core application is under the MIT licence. You can use it commercially, modify it and redistribute it, as long as the licence text stays with the code.
One directory is excluded: cloud/, which holds billing and hosted-service code, is under a separate commercial licence that does not allow offering it to others as a paid service. Self-hosting the core never needs that directory. About OpenShorts.io explains how this hosted version relates to the repository.
To stay current, pull from the upstream repository and rebuild with docker compose up --build. If you change the code, keep your changes on a branch so updates merge cleanly.
10
Self-hosted or online
| Self-hosted | Online at OpenShorts.io | |
|---|---|---|
| Suits | Developers, and teams with footage that cannot be uploaded | Creators who want clips without setup |
| Install | Docker | None |
| Cost | Free under MIT; your hardware and model usage | Free plan, then paid plans |
| Limits | None | Monthly minutes; watermark on the free plan |
| Where video is processed | Your machine, plus the model API you configure | Our servers |
If you would rather not install anything, the same pipeline runs online: free AI clipping tool.
11
Open source clipper questions
Is there an open source AI clipper I can self-host?
Yes. OpenShorts is MIT-licensed and runs with Docker Compose on your own machine. It picks moments from the transcript, reframes them to 9:16 with face tracking and burns in word-level captions.
Where is the OpenShorts GitHub repository?
The source is at github.com/mutonby/openshorts. Clone it with git clone https://github.com/mutonby/openshorts.git and start it with docker compose up --build.
Does the self-hosted build add a watermark or cap minutes?
No. A self-hosted build has no watermark and no minute cap. You pay for your own hardware and for any model API you configure.
Do I need a GPU to run it?
No. The default image is CPU-only. On our 4-core, 8 GB server without a GPU, a 3-minute vertical render took 10 minutes 53 seconds. An NVIDIA card with NVENC makes it much faster.
Can I run it without sending anything to Google?
Mostly. Point LLM_BASE_URL at an OpenAI-compatible server such as Ollama and the moment picker runs locally on the transcript. The automatic layout picker and silent videos still need a Gemini key.
How is OpenShorts.io related to openshorts.app?
OpenShorts.io is an independent deployment of the same MIT repository; it is not operated by openshorts.app.
Sources
- Setup, GPU, local model, MCP and licence details: OpenShorts README
- Timings and the YouTube error: our own runs on 15 and 16 November 2026.