OS OpenShorts GitHub

YouTube to Shorts

Clip a YouTube video with your own OpenShorts install

The hosted app is one route to the same pipeline; this one runs on your machine, which changes which failures you hit. Here is what happens between pasting a link and holding a finished 9:16 file.

Same pipeline, different person paying for the model

The hosted app and this repo run the same software. The difference is who supplies the machine and the API keys: on openshorts.app a YouTube link is fetched and processed on their GPU, while a self-hosted install fetches it with yt-dlp on your own box and scores the transcript with whichever model you configure. Nothing about a YouTube job requires an account on openshorts.app.

That shift matters because most of what goes wrong with a YouTube link only goes wrong on a self-hosted box: the source resolution, the bot check, the model you chose for transcription, and the disk under ./output. This page walks the job in the order the pipeline runs it.

Step 1 — Paste the link, or find out why it will be refused

The Clip Generator in the dashboard takes a public video link or a file upload. Two things cannot be fetched: private or sign-in-only videos, and anything behind a paywall. For those, download the file yourself and upload it instead. The wider list of accepted sources — Vimeo, TikTok, X, Twitch, Kick and others besides YouTube — is on openshorts.app's own YouTube Shorts page, read on 18 November 2026.

One number from that page is worth carrying over: the source needs at least 45 seconds of material before the picker has anything to rank. And for a first run, do not start with the one-hour episode — give it two or three minutes, which tells you the stack is working without waiting through a full render.

Step 2 — The 720p quality gate fires first

Before any download, a URL source is checked against QUALITY_GATE_MIN_HEIGHT. The default is 720, and it only applies to URL sources, never to uploaded files. A YouTube video from 2013 that tops out at 480p gets a warning rather than a silent job: you can let it through, or set the variable to 0 to disable the gate.

This is the first self-host trap that has nothing to do with Docker. A 360p source does not fail the pipeline, it just produces a reframed 9:16 file upscaled from very little, and the face tracker has less to work with.

Step 3 — Transcription, word by word

The audio is transcribed with faster-whisper, or with NVIDIA's Parakeet model when TRANSCRIBE_BACKEND=parakeet. Parakeet only ships in the GPU image, and it falls back to Whisper when it cannot run. Either way you get a timestamp on every word, which is what the captions and the word-level cuts in the editor are built from.

Two variables decide how this goes:

  • WHISPER_MODEL defaults to base. On non-English audio, small is the model the env file points at, at the cost of speed.
  • ASR_GPU_CONCURRENCY should stay at 1. The env file says to keep it at 1, and raising it on a single GPU is how a job runs out of VRAM halfway through.

Step 4 — The moment picker ranks the whole transcript

Every candidate stretch is scored for how well it stands alone; the pipeline asks for 3 to 15 moments of 15 to 60 seconds, each returned with a virality score. The scoring model defaults to Gemini. To keep the transcript on your own machine you can point the picker at any OpenAI-compatible endpoint:

LLM_BASE_URL=http://host.docker.internal:11434/v1
LLM_MODEL=qwen2.5:14b

Three settings around that are worth knowing before you tune anything: Ollama needs OLLAMA_CONTEXT_LENGTH=16384 because its default context is far too small for a transcript, the batch size is LLM_SCORE_BATCH=3, and the per-call timeout is LLM_TIMEOUT=600 seconds. A local 14B model on CPU is slow — expect the scoring step, not the render, to be where the wall-clock time goes.

One limit survives the switch: the frame-based stages still want Gemini. The layout picker and the silent-video path look at frames, and a text model cannot do that job. Run with no Google key at all and those two paths are the ones you lose.

Step 5 — Four ways to fill a vertical frame

The reframing is per scene, and the pipeline picks one of four layouts:

Layout What it does When it appears
TRACK Face-tracked crop that follows the speaker One person on camera
GENERAL Blurred background behind a centred frame Wide shots, no clear subject
SPLIT Two speakers stacked, captions on the seam A conversation
SCREENCAST Screen above or below the presenter Tutorials and demos

Tracking is MediaPipe plus YOLOv8. The layout is chosen per video, and it can be forced from the dashboard when the pick is wrong — which happens most often on a screencast that the model reads as a talking head.

Step 6 — Captions, a hook line, and titles

Each clip comes out with captions burned in from the word-level transcript, an opening hook line written from what is said in that clip, and its own title and description. The hook is editable in wording, font, size and position, so a line that lands on someone's face is a two-minute fix rather than a re-render.

Every clip also opens in the editor: source and program monitors side by side with the transcript underneath, click a word to move a cut, add a segment, change the framing, re-render. That editor is the part separating this from a one-click trimmer, and it is the same editor in both editions.

Step 7 — Where the files land

Finished clips, thumbnails and intermediate media appear in ./output in your clone, because the compose file mounts that folder. Disk usage grows quietly there — the install guide covers the mount and the cleanup, and troubleshooting covers what to do when it fills a disk mid-job.

The variables a YouTube job actually obeys

Everything below has a default already working in .env.example. Change one at a time, and only when the symptom points at it:

Variable Default Change it when
QUALITY_GATE_MIN_HEIGHT 720 Your sources are older and lower-resolution than that
YOUTUBE_COOKIES unset YouTube answers the download with a bot check (paste Netscape-format cookies)
WHISPER_MODEL base The audio is not English
TRANSCRIBE_BACKEND whisper You have the GPU image and want Parakeet
ASR_GPU_CONCURRENCY 1 Leave it alone on a single GPU
FFMPEG_ENCODER x264 A usable GPU is present; auto probes NVENC once at start-up
RATE_LIMIT_PROCESS 60/3600 You queue long batches from one machine
PAID_PROXY_DAILY_MB 500 You rely on the paid proxy and hit its UTC-day ceiling
DEBUG_LOGS unset You need the yt-dlp and ffmpeg output in the UI

RATE_LIMIT_PROCESS is the one that surprises people: sixty processing requests an hour per IP is plenty for a dashboard, and not enough for a script that submits a back catalogue. The rate limiter switches off entirely with RATE_LIMIT_ENABLED=0, which is sane behind your own firewall and unwise on a public instance.

What it does not do

  • It does not pick music or trending sounds. The audio is the source's own.
  • It does not set the related-video link in YouTube Studio. A Short points at the full episode from that field, and setting it by hand is the one step worth doing yourself.
  • It does not run Autopilot. Clipping every new upload on its own is a hosted paid feature; self-hosted, you start each job.
  • It does not post to your channels unless you bring an Upload-Post key. The cloud's paid tiers wire publishing up; self-hosted needs your own account.
  • It does not promise views. It finds the moments most likely to stand alone. The feed decides the rest.

Clipping a batch instead of one

The dashboard is the right tool for one video. For a back catalogue, the same pipeline is reachable over /mcp on your own machine: process_video takes target_clips from 1 to 15, clip_min_seconds from 5 to 175 and clip_max_seconds from 10 to 180, and tells you how many clips it produced. Webhooks are signed HMAC-SHA256 in X-OpenShorts-Signature. The MCP page has the eight tools, the auth headers and the error codes.

Whose videos you can turn into Shorts

Yours, and videos you have the rights to. A clip cut from someone else's upload without permission gets claimed or removed like any reupload — the licence of the source is your problem to check, not the software's. If you want to test the pipeline on material you did not shoot, a CC BY video is the version that carries its permission in writing.

If the job stalls

A YouTube link that downloads on your laptop and not in the container is a cookie problem, not a Docker problem. A job that renders for an hour is usually a CPU encode of a long source, not a hung process. The nine failures that account for most of these cases, each mapped to the variable that fixes it, are on the troubleshooting page.