SupoClip Hands-on: Automatically Convert Long Videos to Vertical Shorts
SupoClip solves a very direct problem: given a long video—podcast, interview, livestream replay—it automatically finds the 3 to 7 clips with the most viral potential, scores them by appeal, and renders them into 9:16 vertical short videos with word-by-word captions, face-centered cropping, and title hooks. The whole process runs on your own hardware, with no watermark and no platform lock-in.
The technical pipeline is split into five stages: AssemblyAI or Whisper for speech-to-text to get word-level timestamps; an LLM selects highlight clips from the transcript and gives ratings; face detection decides who is placed in the center of the vertical frame; captions display word by word according to the word timeline; finally FFmpeg stitches and exports. The frontend is Next.js, the backend is FastAPI, background tasks are executed by ARQ workers pulling from a Redis queue, and PostgreSQL stores user and task data.
Core Dependencies and Environment
First, confirm the basic prerequisites:
- Git
- Docker Engine or Docker Desktop with the Compose plugin
- At least 10GB of free disk space (video files, model caches, and rendering intermediate files all take up space)
- A CPU can handle it, but transcription and rendering stages will be slower; with an NVIDIA GPU you can disable
BACKEND_CPU_ONLYto speed up
Two required keys:
- AssemblyAI API key: for transcription, default path
- A key from one LLM provider: Google, OpenAI, Anthropic, or OpenRouter, choose any one
For a fully local setup, you can switch transcription to Whisper and the clip selection model to Ollama, and then you don't need any API keys.
Project Structure Tree
supoclip/
├── frontend/ # Next.js frontend, port 3107, proxies auth requests to backend
├── backend/ # FastAPI backend, port 8000, includes /docs interactive API docs
├── worker/ # ARQ background task process, handles transcription, analysis, and rendering
├── mcp/ # MCP server, for use by Claude/Cursor
├── docs/ # Setup, configuration, troubleshooting, and other docs
├── scripts/ # Operational scripts like database repair
├── docker-compose.yml # Orchestrates five services: frontend/backend/worker/postgres/redis
└── .env.example # Environment variable template
Data lives in named volumes: postgres_data, redis_data, uploads, and clips. The backend also mounts two local directories, backend/fonts and backend/transitions, which hold caption fonts and transition assets respectively.
Step-by-Step Deployment Guide
1. Clone the Repository and Prepare the Environment File
git clone https://github.com/FujiwaraChoki/supoclip.git
cd supoclip
cp .env.example .env
Edit .env and fill in at least these three items:
ASSEMBLY_AI_API_KEY=your_assemblyai_key
LLM=google-gla:gemini-3-flash-preview
GOOGLE_API_KEY=your_google_key
2. Configure the Highlight Selection Model
The LLM variable determines which model helps you pick clips. Besides cloud models like Gemini, GPT, and Claude, you can also use the ollama: prefix to point to any service that is compatible with the v1/chat/completions protocol. For example, use Defapi to connect to a local model:
LLM=ollama:your_model_id
OLLAMA_BASE_URL=https://api.defapi.org/v1
OLLAMA_API_KEY=your_defapi_key
SupoClip's ollama: prefix just selects the client type; it doesn't force you to run Ollama locally. In the code, OllamaProvider uses AsyncOpenAI to accept a base URL and API key, so as long as the target service is compatible with the OpenAI chat completion protocol, it will work. Defapi is one such service, at roughly half the price of official channels, and almost all models are compatible with the three protocols: v1/chat/completions, v1/messages, and v1beta/models/. Whether clip selection works depends on real testing; transcription and AI editing in the editing studio remain separate paths.
3. Build and Start
./start.sh
If you can't wait for the script, you can do it manually:
docker-compose up -d --build
During the first build, it will pull images and install dependencies; on a CPU machine this may take a few minutes. Monitor progress with:
docker-compose logs -f
When you see all five services become healthy, it's up:
docker-compose ps
4. Check Service Health Status
Open these addresses to confirm:
- Frontend: http://localhost:3107
- Backend health check: http://localhost:8000/health
- Interactive API documentation: http://localhost:8000/docs
The docker-compose ps output should show five containers: supoclip-frontend, supoclip-backend, supoclip-worker, supoclip-postgres, and supoclip-redis.
5. Create an Account and Upload a Video
Open the frontend homepage in your browser and register an account. The homepage supports two types of input: paste a YouTube/Twitch/Kick link, or directly upload a local video file. Note that the upload limit defaults to 4GB, enough for a full 1080p video at a normal bitrate.
6. Preview, Edit, and Export Vertical Shorts
After submitting a task, the task page shows real-time progress: the status of each stage—transcription, AI analysis, rendering—will be pushed. When complete, you can see the duration of each clip, a transcript excerpt, the AI's selection rationale, and a virality score.
Click into the editing studio to make these adjustments:
- Drag the edges of a clip to trim the start and end
- Split a long clip into multiple shorter segments
- Merge multiple clips
- Rewrite caption text
- Switch caption styles (font, animation, size, color)
- Export with platform presets: TikTok, Reels, Shorts
When exporting, choose "Vertical output," and you'll get a 9:16 vertical final video with face-centered cropping and word-by-word captions already burned in.
Common Troubleshooting
Frontend page won't open
Check the host port. The template defaults to FRONTEND_PORT=3107. If you upgraded from an older version and .env lacks this variable, it falls back to 3001. Use docker-compose port frontend 3107 to see the actual mapping.
Login reports "Invalid origin"
NEXT_PUBLIC_APP_URL and BETTER_AUTH_URL must exactly match the browser address, including the protocol and port. localhost and 127.0.0.1 are two different origins. To access from a different domain or port, set BETTER_AUTH_TRUSTED_ORIGINS as a comma-separated explicit list; wildcards are not supported.
Task stays stuck in "queued"
First check the worker logs. docker-compose logs -f worker will directly expose any errors. Then check the worker heartbeat with curl -f http://localhost:8000/health/worker. A 503 response means the worker is unresponsive or Redis is unreachable. The ARQ heartbeat expires approximately every 31 seconds.
Transcription stuck at 30% and not moving
This stage is calling AssemblyAI. Check the backend logs to confirm whether the API key is valid and the account quota is sufficient. There's an overall timeout budget for status polling, default 900 seconds; if it times out, it retries the same transcription task without double billing. For long videos, you can increase ASSEMBLY_AI_HTTP_TIMEOUT_SECONDS.
Clip selection model errors or output format is incorrect
The LLM prefix and provider key must match: ollama: pairs with OLLAMA_BASE_URL and OLLAMA_API_KEY, google-gla: pairs with GOOGLE_API_KEY, and so on. If a local model returns malformed JSON, Agent will retry up to two times (output_retries=2). Switching to a model with stronger instruction-following abilities usually solves the problem.
Registration reports "Failed to create account"
Most likely the database schema is behind the code. Run the idempotent repair script; it only adds columns and doesn't touch existing data:
docker compose exec -T postgres psql -U supoclip -d supoclip < scripts/selfhost-schema-repair.sql
Never run prisma db push or prisma migrate deploy against this database; the backend manages tables that Prisma doesn't know about, and db push will drop them.
Further Reading / Advanced Directions
- Fully local route: Change
TRANSCRIPTION_PROVIDERtowhisper, and useLLM=ollama:...with a local Ollama service. Note that the default Ollama address inside Docker ishttp://host.docker.internal:11434/v1, and the host's Ollama must listen on the corresponding port. - MCP integration: The repository's
mcp/directory provides an MCP server, allowing you to call SupoClip's editing capabilities directly from clients like Claude or Cursor. - REST API: Generate an API key under
/settings/api-keysand call the backend endpoints directly, suitable for scripted batch processing. - B-roll assets: Set
PEXELS_API_KEY, and after AI clip selection, it will automatically match free stock videos from Pexels as b-roll shots. - License boundary: The current version is under the SupoClip Noncommercial Source License 1.1. Non-commercial use and individual creators monetizing their own media are free. Companies, institutions, teams, or editing services must apply for written permission via email. Read the
LICENSEfile carefully before you start, especially the definition of "Individual Creators."