SupoClip self-hosting and AI video clipping pipeline

What SupoClip Does for Long-Form Video

SupoClip addresses the repetitive work involved in turning a podcast, talk, or stream VOD into short vertical videos. The input is a long video with spoken content. The output is a set of selected segments rendered as vertical 9:16 clips, with face-centered cropping, word-synced subtitles, hook titles, and optional B-roll. The README also describes a built-in editor for trimming, splitting, and merging clips, followed by export using TikTok, Reels, and Shorts presets.

The intended users are creators who publish short-form video, teams that want to control their processing environment, and developers who want to inspect or modify the pipeline. The project presents itself as an alternative to OpusClip because it can be self-hosted, does not add watermarks, and avoids reliance on a metered service plan. It also offers a hosted web app and an iOS app that use the hosted pipeline.

This is not a general-purpose video editor presented as a single-file command. The documented path involves a frontend, backend API, worker, queue, AI providers, and video processing pipeline. The project is therefore aimed at people who need clipping automation as an application workflow rather than a manual desktop editing task.

How SupoClip Selects and Renders Clips

The documented processing flow starts with transcription. AssemblyAI is the default transcription provider and supplies word-level timing and speaker diarization. The `.env.example` file also documents `whisper` for local transcription and `youtube_captions` for YouTube-sourced videos. The spoken language can be detected automatically or selected with an AssemblyAI language code.

After transcription, an LLM analyzes the transcript and selects three to seven segments. The README says Gemini, GPT, Claude, or a local Ollama model can be used. Each selected clip receives scores for hook, engagement, value, and shareability. This score layer is part of SupoClip's core product behavior, but the README does not describe the scoring formula or evaluation criteria.

The rendering stage converts a selected segment into a vertical composition. Face detection is used to keep the speaker centered, while word-level timestamps drive subtitles. An AI-written hook title is burned into the opening seconds. Pexels footage can optionally be added as B-roll, and transition effects are available.

The repository documentation identifies the runtime pieces as a frontend, API, worker, queue, and pipeline. It also documents a REST API, API-key authentication through `/settings/api-keys`, and an MCP server in `mcp/`. The README does not provide a complete internal request diagram, so the precise queue payload and retry behavior cannot be confirmed.

Docker Compose Installation and First Self-Hosted Run

The documented self-hosting path requires Docker, an AssemblyAI API key, and one LLM provider key. Clone the repository and enter its directory with these commands:

git clone https://github.com/FujiwaraChoki/supoclip.git
cd supoclip

Create a `.env` file in the repository root. The README gives the following minimal example for AssemblyAI and Google:

ASSEMBLY_AI_API_KEY=your_assemblyai_api_key
LLM=google-gla:gemini-3-flash-preview
GOOGLE_API_KEY=your_google_api_key

Start the services with the documented Compose command:

docker-compose up -d

The README says the first startup takes a few minutes. Follow the logs while services initialize:

docker-compose logs -f

Once the application is healthy, open `http://localhost:3107` and create an account. The backend API is available at `http://localhost:8000`, with interactive documentation at `/docs`. The Compose file maps the frontend to `127.0.0.1:${FRONTEND_PORT:-3001}:3107`, while the README explains that new self-hosted installations use `FRONTEND_PORT=3107`; existing deployments may need to preserve port `3001` because their reverse proxy already depends on it.

The configuration also includes a 12 GB default local upload limit through `MAX_VIDEO_UPLOAD_BYTES=12000000000`. The environment file notes that the frontend client-side cap must match this value or uploads can return HTTP 413. For a real first use, upload a long video, monitor processing progress in the browser, inspect the selected clips, adjust them in the editor if needed, and export a TikTok, Reels, or Shorts preset. The README does not give a CLI command for this workflow, so the browser application is the documented first-use interface.

Provider Choices and CPU-Only Docker Operation

SupoClip does not require a single cloud vendor for every stage, but the default path still depends on external services. AssemblyAI is selected by default in `.env.example`, and the LLM provider must also be configured. The environment file documents OpenAI, OpenRouter, Google, Anthropic, and local Ollama options, although the visible portion does not show the complete variable for every provider. Provider names and example values should be copied from `docs/configuration.md` rather than inferred from the visible README excerpt.

For a fully local arrangement, the README points to its self-hosting tutorial for Whisper and Ollama, including the Docker networking required by Ollama. This can reduce dependence on cloud APIs for transcription and analysis, but it transfers operational responsibility to the host. The README does not document local model hardware requirements or processing-time limits.

There is also a CPU-specific setting. `.env.example` sets `BACKEND_CPU_ONLY=true` and explains that this avoids CUDA or NVIDIA dependency downloads on CPU-only Docker hosts, including Macs. Existing deployments without the setting retain their current Torch variant. That choice is useful for portable installation, but it does not establish predictable throughput on every CPU. Video size, model choice, face detection, subtitle generation, and rendering all affect the work required.

Self-Hosting Boundaries and Processing Risks

The largest operational constraint is that self-hosting moves several dependencies into the administrator's environment. Docker services need to start correctly, the frontend and backend must communicate, the worker and queue must be available, and the selected AI providers must accept the requests. The repository links `docs/troubleshooting.md` for common failure modes, but the README does not state recovery guarantees or a supported rollback procedure.

Uploads have a concrete boundary. Local uploads are capped at approximately 12 GB by default, and the environment file warns that the client-side limit must match the server setting. AssemblyAI also has `ASSEMBLY_AI_HTTP_TIMEOUT_SECONDS=900`, which is relevant to larger uploads. This timeout does not establish a maximum processing duration because transcription, analysis, and rendering may involve separate waits.

Provider availability is another limitation. A cloud transcription failure or LLM key failure can stop processing even when the application itself is healthy. The project documents configuration choices and troubleshooting references, but it does not promise offline operation with every combination of settings. Fully local operation requires more than self-hosting the containers, because Whisper, Ollama, model downloads, and the host's networking configuration must all be set up according to the linked tutorial.

SupoClip also includes hosted web and iOS options. Those routes avoid managing the infrastructure, but they are not equivalent to a self-hosted deployment. The choice affects where processing runs, which credentials are needed, and who operates upgrades.

SupoClip Compared with a Hosted Clipping Service

The clearest alternative described by the project is a hosted clipping service such as OpusClip. The difference is not simply the list of editing effects. SupoClip is designed for organizations or individuals that want to run the processing stack on their own hardware and retain control over configuration, source inspection, and usage limits. Its Docker Compose setup exposes the frontend, backend API, worker, and queue as parts they can operate.

A hosted service can remove that infrastructure work. SupoClip itself offers `www.supoclip.com` and an iOS app for users who prefer the hosted pipeline. That option still follows SupoClip's product and account model, while a self-hosted deployment uses the operator's own infrastructure and credentials. The README does not compare hosted limits, privacy terms, export behavior, or pricing against OpusClip, so those details should not be inferred.

For developers, the REST API and MCP server are meaningful differences from a closed workflow. They provide documented integration surfaces, while the browser editor remains available for human review. The trade-off is that integrating a self-hosted system requires more operational work than signing in to a managed application.

Testing, Maintenance, and AGPL-3.0 Implications

The repository documents a test command that covers backend and frontend tests:

make test

The Makefile defines `make test` as `test-backend test-frontend`. Backend tests use `uv` and `pytest`; frontend tests use `pnpm run test:coverage`. Separate targets include `make test-e2e`, `make check`, and `make test-ci`. The documented test environment references PostgreSQL and Redis, so running the full test stack may require those services. The README also lists Playwright as part of the broader test suite.

The repository is not archived, and the last push was on 2026-10-16. However, no GitHub releases are published. That distinction matters for operators: there is no release-based upgrade path documented by the repository. A deployment should record the checked-out commit and inspect changes before pulling new code.

SupoClip is released under AGPL-3.0. The README says the project is open source and can be forked and extended, but that statement is not legal advice. Operators modifying the software, serving it over a network, or redistributing it should review `LICENSE` and the contribution terms. The README also says contributions are accepted under terms that include a license grant allowing the project owner to sublicense and relicense contributions, so third-party licensing expectations may matter to adopters.

Editorial conclusion

Adopt SupoClip if you want an inspectable, self-hosted video clipping pipeline and can operate Docker, databases, queues, and AI provider integrations. Do not adopt it if you need a documented zero-infrastructure desktop workflow or require a predictable service-level agreement from an open-source deployment. Before adoption, verify your transcription provider, LLM provider, hardware, local upload limit, and required output formats against the documented environment variables. The repository is not archived, and its last push was on 2026-10-16, but it has no GitHub releases, so pin a commit and review upgrade changes before changing a production deployment.

Frequently asked questions

Official sources

1. FujiwaraChoki/supoclip on GitHub
2. Issues
3. License: AGPL-3.0
4. Project website
5. README