Skip to content
Back to search

openshorts.io

OpenShorts.io: open source AI video clipper, a free OpusClip alternative. Use it free online at openshorts.io or self-host with Docker: long videos to vertical Shorts with face tracking and word-level captions. MIT, fork of mutonby/openshorts.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/xspring1982--openshorts-io/badge.svg)](/listings/xspring1982--openshorts-io)

HTML

<a href="/listings/xspring1982--openshorts-io"><img src="/api/listings/xspring1982--openshorts-io/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You need Docker with Docker Compose and a [Gemini API key](https://aistudio.google.com/app/apikey). You can instead point the moment picker at a local OpenAI-compatible LLM (see below).

git clone https://github.com/xspring1982/openshorts.io.git openshorts && cd openshorts
cp .env.example .env          # optional: S3 backup, GPU, the options above
docker compose up --build

Open <http://localhost:5175>, enter your Gemini key in **Settings**, and upload a video or paste a link in the **Clip Generator**. AI Shorts, YouTube Studio and social posting need their own keys (fal.ai, ElevenLabs, Upload-Post), as upstream documents.

From the command line

The pipeline is `main.py`, and you can run it directly inside the backend container:

docker exec -it openshorts-backend python main.py -i /app/uploads/talk.mp4 -o /app/output/talk \
  --aspect 4:5
docker exec -it -e AUDIO_FIRST=1 -e CAPTION_PRESET=pill openshorts-backend \
  python main.py -u "https://www.youtube.com/watch?v=..." -o /app/output/yt

Each clip lands in the output folder as `<title>_clip_N.mp4`, together with `<title>_metadata.json`. The metadata holds each clip's range, title, hook, TikTok and Instagram descriptions, a predicted score and the reason for it.

GPU

On an NVIDIA machine, build with `GPU=1` and give the container the card, as described in upstream's [GPU section](https://github.com/mutonby/openshorts#5-gpu-acceleration-optional-nvidia). An 8-minute video then clips in about a minute instead of 5 to 8. Without a GPU of your own, use the Modal backend:

pip install modal && modal token new
modal secret create openshorts GEMINI_API_KEY=<key>
modal deploy -m gpu_modal.app
python -m gpu_modal render talk.mp4 -o clips/ --aspect 4:5

Measured on the hosted service: a 10-minute source took 111 s on an L4 for 6 clips, which cost $0.034. One production hour averaged **$0.022 per job**. Costs, limits and the A10 numbers are in [gpu_modal/README.md](gpu_modal/README.md).

Local LLM instead of Gemini

Set `LLM_BASE_URL` (Ollama, vLLM, LM Studio...) and `LLM_MODEL`. The transcript then never leaves your machine. Gemini is then needed only for layout picking and for silent videos.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 166 lines
  1. # OpenShorts.io — open source AI video clipper
  2. Turn long videos (podcasts, talks, interviews, streams) into vertical short
  3. clips with face tracking, animated captions and a hook line: a free,
  4. MIT-licensed alternative to OpusClip.
  5. **Two ways to use it:**
  6. - **Online, no install:** [openshorts.io](https://openshorts.io). Paste a
  7. YouTube link and get captioned 9:16 Shorts. The free plan covers
  8. 15 minutes of video a month, no card needed; paid plans start at
  9. $11.90 a month ([pricing](https://openshorts.io/pricing)). There is also a
  10. hosted [API and MCP server](https://openshorts.io/api) for Claude, Cursor
  11. and other agents.
  12. - **Self-hosted, free:** this repository, with Docker. No watermark, no
  13. minute cap; you bring a Gemini API key (see [Quick start](#quick-start-docker)).
  14. This is the OpenShorts.io open source repository: the self-hostable
  15. clipping pipeline behind [OpenShorts.io](https://openshorts.io), maintained
  16. as a fork of
  17. [OpenShorts](https://github.com/mutonby/openshorts) by mutonby, which is
  18. MIT-licensed. It keeps the whole upstream application:
  19. the clip generator, the dashboard, AI Shorts, YouTube Studio, the MCP server
  20. and the API. On top of that it adds the generic improvements we built while
  21. running the pipeline in production at [OpenShorts.io](https://openshorts.io):
  22. | Change | What it does | Turn it on |
  23. |---|---|---|
  24. | **Aspect ratios** | 4:5 and 16:9 (or any W:H) besides 9:16 and 1:1, with captions and the hook sized for each frame | `OUTPUT_ASPECT=4:5` or `main.py --aspect 4:5` |
  25. | **Caption look per run** | Any of upstream's caption presets, your active-word colour, your font | `CAPTION_PRESET=hormozi`, `CAPTION_HIGHLIGHT=#00E0FF`, `CAPTION_FONT=...` |
  26. | **CJK and right-to-left captions** | No spaces between Chinese or Japanese words, CJK counted as double width, bidi for Arabic and Hebrew, a matching Noto font per language | automatic |
  27. | **Audio-first download** | YouTube links fetch only the audio, pick the moments, then fetch only those ranges of the video | `AUDIO_FIRST=1` or `main.py --audio-first` |
  28. | **Groq transcription** | Hosted Whisper large-v3-turbo in seconds, with local faster-whisper as the fallback | `TRANSCRIBE_BACKEND=groq`, `GROQ_API_KEY` |
  29. | **Gemini resilience** | About three minutes of retries during "503 high demand", alternating with a fallback model | on by default (`GEMINI_MAX_ATTEMPTS`, `GEMINI_FALLBACK_MODELS`) |
  30. | **LLM cost meter** | One JSON line per Gemini call with tokens and cost | `GEMINI_USAGE_FILE=/path/usage.jsonl` |
  31. | **Reuse picks** | Re-render the same moments (for example at another ratio) without a new LLM call | `main.py --clips old_metadata.json` |
  32. | **Modal GPU backend** | Optional serverless rendering on L4/A10, billed per second, with a CPU fallback | [`gpu_modal/`](gpu_modal/README.md) |
  33. Each change is a separate commit on top of upstream, with tests. See
  34. [CHANGELOG.md](CHANGELOG.md).
  35. > **Hosted version:** if you would rather not run it yourself,
  36. > [OpenShorts.io](https://openshorts.io) runs this pipeline on GPUs. Paste a
  37. > YouTube, TikTok, Instagram or Facebook link, or use its API and MCP server.
  38. ## Quick start (Docker)
  39. You need Docker with Docker Compose and a
  40. [Gemini API key](https://aistudio.google.com/app/apikey). You can instead point
  41. the moment picker at a local OpenAI-compatible LLM (see below).
  42. ```bash
  43. git clone https://github.com/xspring1982/openshorts.io.git openshorts && cd openshorts
  44. cp .env.example .env # optional: S3 backup, GPU, the options above
  45. docker compose up --build
  46. ```
  47. Open <http://localhost:5175>, enter your Gemini key in **Settings**, and upload
  48. a video or paste a link in the **Clip Generator**. AI Shorts, YouTube Studio
  49. and social posting need their own keys (fal.ai, ElevenLabs, Upload-Post), as
  50. upstream documents.
  51. ### From the command line
  52. The pipeline is `main.py`, and you can run it directly inside the backend
  53. container:
  54. ```bash
  55. docker exec -it openshorts-backend python main.py -i /app/uploads/talk.mp4 -o /app/output/talk \
  56. --aspect 4:5
  57. docker exec -it -e AUDIO_FIRST=1 -e CAPTION_PRESET=pill openshorts-backend \
  58. python main.py -u "https://www.youtube.com/watch?v=..." -o /app/output/yt
  59. ```
  60. Each clip lands in the output folder as `<title>_clip_N.mp4`, together with
  61. `<title>_metadata.json`. The metadata holds each clip's range, title, hook,
  62. TikTok and Instagram descriptions, a predicted score and the reason for it.
  63. ### GPU
  64. On an NVIDIA machine, build with `GPU=1` and give the container the card, as
  65. described in upstream's
  66. [GPU section](https://github.com/mutonby/openshorts#5-gpu-acceleration-optional-nvidia).
  67. An 8-minute video then clips in about a minute instead of 5 to 8. Without a GPU
  68. of your own, use the Modal backend:
  69. ```bash
  70. pip install modal && modal token new
  71. modal secret create openshorts GEMINI_API_KEY=<key>
  72. modal deploy -m gpu_modal.app
  73. python -m gpu_modal render talk.mp4 -o clips/ --aspect 4:5
  74. ```
  75. Measured on the hosted service: a 10-minute source took 111 s on an L4 for 6
  76. clips, which cost $0.034. One production hour averaged **$0.022 per job**.
  77. Costs, limits and the A10 numbers are in
  78. [gpu_modal/README.md](gpu_modal/README.md).
  79. ### Local LLM instead of Gemini
  80. Set `LLM_BASE_URL` (Ollama, vLLM, LM Studio...) and `LLM_MODEL`. The
  81. transcript then never leaves your machine. Gemini is then needed only for
  82. layout picking and for silent videos.
  83. ## Configuration
  84. Everything upstream documents in `.env.example` still applies. The fork adds:
  85. | Variable | Default | |
  86. |---|---|---|
  87. | `OUTPUT_ASPECT` | `9:16` | output frame; `CAPTION_SCALE`, `CAPTION_CHARS`, `CAPTION_MARGIN_V`, `HOOK_WIDTH` override the per-ratio caption sizing |
  88. | `CAPTION_PRESET` | `default` | `hormozi`, `pill`, `lime`, `oneword`, `cine`, `clean` |
  89. | `CAPTION_HIGHLIGHT` | preset colour | `#RRGGBB` |
  90. | `CAPTION_FONT` | per language | any installed font |
  91. | `AUDIO_FIRST` | off | `1` for YouTube links; `SECTION_PAD` (2 s) and `SECTION_PARALLEL` (6) tune it |
  92. | `TRANSCRIBE_BACKEND` | `whisper` | `groq` (needs `GROQ_API_KEY`), or upstream's `parakeet` |
  93. | `GEMINI_MAX_ATTEMPTS` | 8 | tries per Gemini stage call |
  94. | `GEMINI_FALLBACK_MODELS` | `gemini-flash-lite-latest` | comma-separated, `none` to disable |
  95. | `GEMINI_USAGE_FILE` | unset | path of the per-call cost log |
  96. The dashboard does not show the new options yet. Set them in `.env` for the
  97. backend, or per run on the command line.
  98. ## Limits and differences from upstream
  99. - **No `cloud/` directory.** Upstream's billing, accounts and hosted-service
  100. code (`cloud/`) is under a separate commercial license, so this fork does
  101. not include it, in any commit. The rest runs without it: two imports in
  102. `app.py` became optional, `queue_mode_off.py` stands in for the queue
  103. policy, and the tests that need `cloud/` are skipped. `BILLING_ENABLED`
  104. mode does not work here.
  105. - **Audio-first jobs keep only the picked ranges.** The clip editor's
  106. re-render of other parts of the video reports the source as gone for those
  107. jobs.
  108. - **The new options are not in the dashboard.** They are environment
  109. variables and command-line flags only.
  110. - **YouTube downloads** depend on your IP, cookies and yt-dlp's current
  111. state, as upstream. Datacenter IPs, Modal's included, are often blocked.
  112. ## Staying close to upstream
  113. This fork tracks upstream's `main`. To make updates easy to merge, the fork's
  114. changes are small, marked with `Fork:` comments, and kept in new modules where
  115. possible (`output_aspect.py`, `audio_first.py`, `groq_asr.py`,
  116. `usage_meter.py`, `queue_mode_off.py`, `gpu_modal/`). See
  117. [CONTRIBUTING.md](CONTRIBUTING.md) for the sync procedure.
  118. ## Development
  119. ```bash
  120. pip install pytest pillow httpx pydantic sqlalchemy greenlet numpy opencv-python-headless \
  121. python-dotenv google-genai fastapi boto3 PyJWT email-validator python-multipart asyncpg
  122. pytest tests/ -q
  123. ```
  124. With the full CPU stack installed (`requirements-cpu.lock` plus torch), the
  125. tests that import `main.py` run as well.
  126. ## License and credit
  127. MIT, see [LICENSE](LICENSE) and [NOTICE](NOTICE). OpenShorts is by mutonby
  128. and its contributors; the original project, its documentation and its hosted
  129. service live at [github.com/mutonby/openshorts](https://github.com/mutonby/openshorts).
  130. The full upstream history is kept in this repository, minus `cloud/`. This
  131. fork is maintained by the OpenShorts.io team. It is not affiliated with or
  132. endorsed by the upstream project.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.