# OpenShorts

Self-hosted AI clip generator with an eight-tool MCP server for clipping, captioning, and publishing shorts.

Turns long videos into 9:16 clips with Gemini moment detection, face-tracked reframing, faster-whisper subtitles, ElevenLabs dubbing, and Upload-Post publishing. Runs from docker compose on your own machine or as a hosted plan; both expose the same /mcp endpoint.

Alternative to: Opus Clip, Vizard

- Capabilities: adaptable, operable
- Vertical: video-streaming
- Shape: business-app
- Form factor: web-app
- Execution model: hybrid
- Provenance: unknown (recorded, never ranked)
- Repo: https://github.com/mutonby/openshorts (MIT (cloud/ directory under a commercial license)), 3833 stars, last commit 2026-09-02
- Last activity: 2026-09-02
- Page: apps/mutonby--openshorts.html
- JSON: apps/mutonby--openshorts.json

## Use it when

- I publish a weekly podcast and want clips cut, captioned, and posted without a $20/mo clipper subscription
- I want an agent to turn every new livestream VOD into shorts overnight on my own GPU box

## Gotchas

- The cloud/ directory is under a commercial license, not MIT; GitHub shows the license as 'other' for that reason
- CPU-only by default: 5 to 8 minutes per 8-minute video; NVIDIA Container Toolkit needed for NVENC
- Self-hosted /mcp only answers while your machine is on; the hosted endpoint at mcp.openshorts.app needs an osk_ API key
- Provider keys go into the dashboard Settings, not .env

## Editions

- Self-hosted: Free, open source
  - source: https://github.com/mutonby/openshorts
  - container: docker compose up --build
- Cloud Free: Free, closed source
  - hosted: https://www.openshorts.app/
- Cloud paid: $12 per month, closed source
  - hosted: https://www.openshorts.app/

## Adaptable: make it yours

Effort: config-only (25 things to edit)

Copy .env.example to .env. Point LLM_BASE_URL and LLM_MODEL at Ollama or any OpenAI-compatible server to drop the Gemini dependency; tune WHISPER_MODEL, TRANSCRIBE_BACKEND, FFMPEG_ENCODER, and QUALITY_GATE_MIN_HEIGHT; add AWS_S3_BUCKET for backup. Provider keys for Gemini, fal.ai, ElevenLabs, and Upload-Post are entered in the dashboard Settings page.

- Env vars: LLM_BASE_URL, LLM_MODEL, LLM_API_KEY, LLM_SCORE_BATCH, LLM_TIMEOUT, WHISPER_MODEL, WHISPER_DEVICE, WHISPER_COMPUTE, TRANSCRIBE_BACKEND, ASR_GPU_CONCURRENCY, FFMPEG_ENCODER, QUALITY_GATE_MIN_HEIGHT, GEMINI_MODEL_THUMBNAIL, GEMINI_IMAGE_MODEL, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, AWS_S3_BUCKET, AWS_S3_PUBLIC_BUCKET, YOUTUBE_COOKIES, DEBUG_LOGS, PAID_PROXY_DAILY_MB
- Config files: .env, docker-compose.yml, docker-compose.override.yml
- Prompt files: none
- Accounts you'll need: Google AI Studio (Gemini); fal.ai (AI Shorts only); ElevenLabs (dubbing only); Upload-Post (publishing only); AWS (optional S3)

## Operable: what an agent can drive

Operability: official. Interface: mcp at https://www.openshorts.app/mcp (published by the builder, both).

### Reach (partial coverage)

- Generate clips from a long video: reachable. MCP tools process_video, create_upload, get_job_status, list_clips
- Restyle subtitles: reachable. MCP tool add_subtitles (classic or karaoke)
- Recut a clip: reachable. MCP tool recut_clip
- Publish or schedule to TikTok, Instagram, YouTube: reachable. MCP tool publish_clip through Upload-Post
- Check plan quota: reachable. MCP tool get_quota
- Generate AI Shorts with UGC actors: not reachable. No MCP tool covers the AI Shorts pipeline; dashboard only
- YouTube Studio: titles, thumbnails, descriptions: not reachable. No MCP tool; dashboard only
- Dub clips into other languages: not reachable. Dubbing is a dashboard feature; not among the eight MCP tools
- Force a reframing layout per video: not reachable. README: layout forced from the dashboard; no MCP parameter documented

## Code stack

- Languages: Python, TypeScript
- Frameworks: FastAPI, Vite, ffmpeg, MediaPipe, YOLOv8, faster-whisper
- Package manager: pip
- Database: none
- Hosting target: Docker, openshorts.app

## Model stack

- Providers: Google Gemini, any OpenAI-compatible LLM through LLM_BASE_URL, ElevenLabs, fal.ai
- Models: Gemini 3.1 Flash-Lite, faster-whisper, Flux 2 Pro, Hailuo 2.3 Fast
- Keys you need (names only): GEMINI_API_KEY (entered in dashboard Settings), LLM_API_KEY, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
- Prompts live in: none
- Tools: process_video, create_upload, get_job_status, list_clips, get_quota, add_subtitles, recut_clip, publish_clip

## Skills

bundled: A Claude Code plugin that teaches an agent to generate and publish short videos through OpenShorts.
- Paths: skills/openshorts/SKILL.md
- Install: /plugin marketplace add mutonby/openshorts

## Evidence and confidence

- formFactor: README: dashboard at localhost:5175 served by FastAPI backend (confidence 0.95)
- executionModel: README: fixed pipeline; Gemini or a local LLM picks moments and layouts (confidence 0.9)
- operability: openshorts.app/mcp: eight tools, Streamable HTTP, published by OpenShorts; self-host serves the same endpoint (confidence 0.9)
- effort: .env.example documents every variable with comments; docker compose is the only install (confidence 0.9)
- editions: README table: self-hosted free forever MIT; hosted free 20 min/mo with watermark; paid from $12/mo to $59/mo (confidence 0.9)
- active: GitHub pushedAt 2026-09-02
- reach:  (confidence 0.85)

## Open questions

- Does the self-hosted MCP accept a bearer token or run open on localhost only?
- Is the AI Shorts pipeline reachable through the REST API even though it is not an MCP tool?

## Sources

- https://www.openshorts.app/ (sourcing:video-streaming:community)
- https://github.com/mutonby/openshorts (sourcing:video-streaming:community)
- https://www.openshorts.app/mcp (analysis)