Fuck OpusClip.

... because good video clips shouldn't come with ugly watermarks or platform lock-in.

SupoClip gives you AI-powered video clipping capabilities in an open-source package you can run yourself, customize, and inspect. Use the hosted version when you want the convenience of managed infrastructure, or self-host when you want full control.

Want it without the setup? Use the hosted version at www.supoclip.com or grab the iOS app.

• Hosted web app — www.supoclip.com, no infrastructure to run
• iOS app — SupoClip on the App Store, clip from your iPhone with the same hosted pipeline
• Self-host — Docker Compose setup below, AGPL-3.0, unlimited usage on your own hardware
• MCP server — mcp/ exposes SupoClip to Claude, Cursor, and other MCP clients
• REST API — API keys from /settings/api-keys authenticate the backend directly

OpusClip is undeniably powerful. It's an AI video clipping tool that can turn long-form content into viral short clips with features like:

• AI-powered clip generation from long videos
• Automated captions with 97%+ accuracy
• Virality scoring to predict viral potential
• Multi-language support (20+ languages)
• Brand templates and customization

But here's the catch:

• Usage limits: Processing minutes are capped by plan
• Watermarks: Some exports can include platform branding
• Processing limits: Even paid plans have strict minute limits
• Vendor lock-in: Your content and workflows are tied to their platform

SupoClip provides the same core functionality with more control:

→ ✅ Self-Hostable - Run it on your own infrastructure

→ ✅ No Watermarks - Your content stays yours

→ ✅ Open Source - Full transparency, community-driven development

→ ✅ Hosted Option - Use SupoClip without managing servers

→ ✅ Unlimited Usage - Process as many videos as your hardware can handle

→ ✅ Customizable - Modify and extend the codebase to fit your needs

• Docker and Docker Compose
• An AssemblyAI API key (for transcription) - Get one here
• An LLM provider for AI analysis - OpenAI, Google, Anthropic, or Ollama

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

Create a .env file in the root directory:

# Required: Video transcription
ASSEMBLY_AI_API_KEY=your_assemblyai_api_key

# Required: Choose ONE LLM provider and set its API key
# Option A: Google Gemini (recommended - fast & cost-effective)
LLM=google-gla:gemini-3-flash-preview
GOOGLE_API_KEY=your_google_api_key

# Option B: OpenAI GPT-5.2 (best reasoning)
# LLM=openai:gpt-5.2
# OPENAI_API_KEY=your_openai_api_key

# Option C: Anthropic Claude
# LLM=anthropic:claude-4-sonnet
# ANTHROPIC_API_KEY=your_anthropic_api_key

# Option D: Ollama (local/self-hosted)
# LLM=ollama:gpt-oss:20b
# OLLAMA_BASE_URL=  # Optional; defaults to localhost locally, host.docker.internal in Docker
# OLLAMA_API_KEY=your_ollama_api_key  # Optional (Ollama Cloud)

# Optional: Auth secret (change in production)
BETTER_AUTH_SECRET=change_this_in_production

# Optional: DataFast analytics
# Track your deployed domain in DataFast
# NEXT_PUBLIC_DATAFAST_WEBSITE_ID=dfid_xxxxx
# NEXT_PUBLIC_DATAFAST_DOMAIN=your-domain.com
# NEXT_PUBLIC_DATAFAST_ALLOW_LOCALHOST=false

# Optional: Amazon SES for subscription lifecycle emails (hosted/monetized mode)
# AWS_REGION=us-east-1
# AWS_ACCESS_KEY_ID=your_aws_access_key_id
# AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key
# SES_FROM_EMAIL="SupoClip <onboarding@example.com>"

# Optional: YouTube metadata provider
# `yt_dlp` preserves the existing metadata behavior
# `youtube_data_api` uses the official API first, then falls back to yt-dlp
# YOUTUBE_METADATA_PROVIDER=yt_dlp
# YOUTUBE_DATA_API_KEY=your_youtube_data_api_key

docker-compose up -d

This starts:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000 (docs at /docs)
• PostgreSQL: localhost:5432
• Redis: localhost:6379

First-time startup takes a few minutes. Check progress with:

docker-compose logs -f

Wait until you see health checks passing for all services.

Open http://localhost:3000 in your browser, create an account, and start clipping!

If you enable DataFast, also verify that:

• /js/script.js loads from your own app domain
• /api/events requests are proxied through your app domain
• custom goals appear after successful sign-up, sign-in, task creation, billing, or feedback actions

Backend fails to start with API key error:

• Make sure you've set the correct LLM provider AND its corresponding API key in .env
• Default is google-gla:gemini-3-flash-preview which requires GOOGLE_API_KEY
• If using openai:gpt-5.2, you MUST set OPENAI_API_KEY
• If using ollama:*, run Ollama and optionally set OLLAMA_BASE_URL (http://localhost:11434/v1 for local backend runs, http://host.docker.internal:11434/v1 for Docker)
• Rebuild after changing .env: docker-compose up -d --build

Videos stay queued / never process:

• Check worker logs: docker-compose logs -f worker
• Ensure Redis is healthy: docker-compose logs redis
• Verify API keys are correct

YouTube titles or duration lookup is failing:

• YOUTUBE_METADATA_PROVIDER=yt_dlp keeps the old metadata path
• YOUTUBE_METADATA_PROVIDER=youtube_data_api requires YouTube Data API v3 enabled in Google Cloud
• Prefer YOUTUBE_DATA_API_KEY; if it is unset, the backend will try GOOGLE_API_KEY
• The backend will automatically fall back to the other metadata provider if the primary one fails
• videos.list costs 1 quota unit per request

Performance tuning (default is fast mode):

• DEFAULT_PROCESSING_MODE=fast|balanced|quality
• FAST_MODE_MAX_CLIPS=4 to cap clip count in fast mode
• FAST_MODE_TRANSCRIPT_MODEL=nano for fastest transcript model
• View aggregate metrics: GET /tasks/metrics/performance

Prisma errors on Windows:

• Run docker-compose down -v to clear volumes
• Run docker-compose up -d --build to rebuild

Frontend shows database errors:

• Wait for PostgreSQL to fully initialize (check logs)
• The database is automatically created on first run

Font picker is empty / cannot select or upload fonts:

• Add fonts to backend/fonts/ – see backend/fonts/README.md for TikTok Sans and custom fonts
• Ensure BACKEND_AUTH_SECRET is set in .env when using the hosted/monetized setup
• Font upload is Pro-only when monetization is enabled; self-hosted users can upload freely

Subscription emails are not sending:

• Set AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and SES_FROM_EMAIL in .env
• SES_FROM_EMAIL must be a verified identity/domain in Amazon SES
• The backend sends the “thank you for subscribing” email on checkout.session.completed
• The backend sends the “sorry to see you go” email on customer.subscription.deleted

SupoClip now has a layered automated test setup:

• pytest for backend unit and integration tests
• Vitest and Testing Library for frontend route and component coverage
• Playwright for a small seeded browser smoke suite

Repo-level entrypoints:

make test
make test-backend
make test-frontend
make test-e2e
make test-ci

App-level entrypoints:

cd backend && uv sync --all-groups && .venv/bin/pytest
cd frontend && npm install && npm run test:coverage
cd frontend && npm run test:e2e

Local test runs expect PostgreSQL and Redis to be available. The easiest path is to start the stack with docker-compose up -d, then run the commands above. CI runs the same layers in GitHub Actions with Postgres and Redis service containers.

Detailed documentation now lives in docs/.

Start with:

• docs/setup.md
• docs/configuration.md
• docs/app-guide.md
• docs/architecture.md
• docs/api-reference.md
• docs/development.md
• docs/troubleshooting.md

When you run SupoClip with monetization enabled (SELF_HOST=false), subscription lifecycle emails are sent through Amazon SES by the backend:

• checkout.session.completed sends the thank-you-for-subscribing email
• customer.subscription.deleted sends the sorry-to-see-you-go email

Required env vars for this flow:

• AWS_REGION
• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• SES_FROM_EMAIL
• BACKEND_AUTH_SECRET
• STRIPE_SECRET_KEY
• STRIPE_WEBHOOK_SECRET
• STRIPE_PRICE_ID

See CLAUDE.md for detailed development instructions.

SupoClip is released under the AGPL-3.0 License. See LICENSE for details.

Contributions are accepted under the terms in CONTRIBUTING.md, including a license grant that allows the project owner to sublicense and relicense contributed code.