SupoClip 시작하기: 긴 영상을 세로형 숏폼으로 자동 변환
SupoClip이 해결하는 문제는 매우 직접적입니다. 팟캐스트, 인터뷰, 라이브 다시보기 같은 긴 영상에서 전파 가능성이 가장 높은 3~7개 클립을 자동으로 찾아 매력을 점수로 매기고, 단어별 자막, 얼굴 중앙 크롭, 제목 훅이 포함된 9:16 세로형 숏폼으로 렌더링합니다. 전체 프로세스는 자체 하드웨어에서 실행되며, 워터마크나 플랫폼 종속이 없습니다.
기술 파이프라인은 다섯 부분으로 나뉩니다. AssemblyAI 또는 Whisper로 음성을 텍스트로 변환해 단어별 타임스탬프를 얻고, LLM이 대본에서 하이라이트 클립을 선택하고 점수를 매기며, 얼굴 감지가 세로 화면에서 누구를 중앙에 배치할지 결정하고, 자막이 단어 타임라인에 따라 단어별로 표시되며, 마지막으로 FFmpeg가 이어붙여 내보냅니다. 프론트엔드는 Next.js, 백엔드는 FastAPI, 백그라운드 작업은 ARQ 워커가 Redis 대기열에서 가져와 실행하며, PostgreSQL이 사용자 및 작업 데이터를 저장합니다.
핵심 의존성 및 환경
먼저 기본 요구 사항을 확인하세요.
- Git
- Docker Engine 또는 Docker Desktop(Compose 플러그인 포함)
- 최소 10GB의 사용 가능한 디스크 공간(비디오 파일, 모델 캐시, 렌더링 중간 파일이 공간을 차지함)
- CPU로도 실행할 수 있지만, 전사 및 렌더링 단계는 느려집니다. NVIDIA GPU가 있으면
BACKEND_CPU_ONLY를 끄면 가속화할 수 있습니다.
필수 키 두 개:
- AssemblyAI API 키: 전사용, 기본 경로
- LLM 제공업체 키: Google, OpenAI, Anthropic 또는 OpenRouter 중 하나
완전히 로컬에서 실행하려면 전사를 Whisper로, 클립 선택 모델을 Ollama로 바꾸면 API 키가 하나도 필요 없습니다.
프로젝트 구조 트리
supoclip/
├── frontend/ # Next.js 프론트엔드, 포트 3107, 인증 요청을 백엔드로 프록시
├── backend/ # FastAPI 백엔드, 포트 8000, /docs 대화형 API 문서 포함
├── worker/ # ARQ 백그라운드 작업 프로세스, 전사, 분석, 렌더링 처리
├── mcp/ # MCP 서버, Claude/Cursor에서 호출용
├── docs/ # 설정, 구성, 문제 해결 등 문서
├── scripts/ # 데이터베이스 수리 등 운영 스크립트
├── docker-compose.yml # 5개 서비스 오케스트레이션: frontend/backend/worker/postgres/redis
└── .env.example # 환경 변수 템플릿
데이터는 이름 있는 볼륨에 저장됩니다: postgres_data, redis_data, uploads, clips. 백엔드는 또한 자막 글꼴과 전환 자산을 위한 backend/fonts 및 backend/transitions 두 로컬 디렉터리를 마운트합니다.
단계별 배포 가이드
1. 저장소 클론 및 환경 파일 준비
git clone https://github.com/FujiwaraChoki/supoclip.git
cd supoclip
cp .env.example .env
.env를 편집하고 최소한 다음 세 항목을 입력합니다.
ASSEMBLY_AI_API_KEY=your_assemblyai_key
LLM=google-gla:gemini-3-flash-preview
GOOGLE_API_KEY=your_google_key
2. 하이라이트 선택 모델 구성
LLM 변수는 클립을 선택할 모델을 결정합니다. Gemini, GPT, Claude와 같은 클라우드 모델 외에도 ollama: 접두사를 사용하여 v1/chat/completions 프로토콜을 지원하는 모든 서비스를 가리킬 수 있습니다. 예를 들어 Defapi를 사용해 로컬 모델에 연결합니다.
LLM=ollama:your_model_id
OLLAMA_BASE_URL=https://api.defapi.org/v1
OLLAMA_API_KEY=your_defapi_key
SupoClip의 ollama: 접두사는 클라이언트 유형만 선택하며, 로컬에서 Ollama를 실행할 필요는 없습니다. 코드에서 OllamaProvider는 AsyncOpenAI를 사용하여 base_url과 API 키를 받으므로, 대상 서비스가 OpenAI 채팅 완성 프로토콜과 호환되면 작동합니다. Defapi가 그러한 서비스이며, 가격은 공식 채널의 약 절반이고, 모든 모델이 기본적으로 v1/chat/completions, v1/messages, v1beta/models/ 세 가지 프로토콜과 호환됩니다. 클립 선택이 작동하는지 여부는 실제 테스트로 확인해야 하며, 전사 및 편집 스튜디오의 AI 편집은 여전히 별도 경로입니다.
3. 빌드 및 시작
./start.sh
스크립트를 기다리기 싫으면 수동으로도 할 수 있습니다.
docker-compose up -d --build
첫 빌드에서는 이미지를 가져오고 종속성을 설치하며, CPU 머신에서는 몇 분이 걸릴 수 있습니다. 다음 명령으로 진행 상황을 확인하세요.
docker-compose logs -f
5개 서비스가 모두 healthy가 되면 시작된 것입니다.
docker-compose ps
4. 서비스 상태 확인
다음 주소를 열어 확인하세요.
- 프론트엔드: http://localhost:3107
- 백엔드 상태 확인: http://localhost:8000/health
- 대화형 API 문서: http://localhost:8000/docs
docker-compose ps 출력에는 supoclip-frontend, supoclip-backend, supoclip-worker, supoclip-postgres, supoclip-redis 다섯 개 컨테이너가 있어야 합니다.
5. 계정 생성 및 비디오 업로드
브라우저에서 프론트엔드 홈페이지를 열고 계정을 등록합니다. 홈페이지는 두 가지 입력을 지원합니다: YouTube/Twitch/Kick 링크 붙여넣기 또는 로컬 비디오 파일 직접 업로드. 업로드 제한은 기본 4GB로, 일반 비트레이트의 1080p 전체 비디오를 저장하기에 충분합니다.
6. 세로형 숏폼 미리보기, 편집 및 내보내기
작업을 제출하면 작업 페이지에 실시간 진행 상황이 표시됩니다: 전사, AI 분석, 렌더링 각 단계의 상태가 푸시됩니다. 완료 후 각 클립의 길이, 전사 발췌, AI 선택 이유, 전파력 점수를 볼 수 있습니다.
편집 스튜디오에 들어가면 다음을 조정할 수 있습니다.
- 클립 가장자리를 드래그하여 앞뒤를 자르기
- 긴 클립을 여러 개의 작은 클립으로 분할
- 여러 클립 병합
- 자막 텍스트 다시 쓰기
- 자막 스타일 전환(글꼴, 애니메이션, 크기, 색상)
- 플랫폼 사전 설정으로 내보내기: TikTok, Reels, Shorts
내보낼 때 "Vertical output"을 선택하면 얼굴 중앙 크롭과 단어별 자막이 이미 포함된 9:16 세로형 완성본을 얻습니다.
일반적인 문제 해결
프론트엔드 페이지가 열리지 않음
호스트 포트를 확인하세요. 템플릿 기본값은 FRONTEND_PORT=3107이며, 이전 버전에서 업그레이드한 경우 .env에 이 변수가 없으면 3001로 폴백합니다. docker-compose port frontend 3107로 실제 매핑을 확인하세요.
로그인 시 Invalid origin 오류
NEXT_PUBLIC_APP_URL과 BETTER_AUTH_URL은 브라우저 주소와 프로토콜 및 포트를 포함해 완전히 일치해야 합니다. localhost와 127.0.0.1은 서로 다른 origin입니다. 다른 도메인이나 포트에 접속하려면 BETTER_AUTH_TRUSTED_ORIGINS에 쉼표로 구분된 명시적 목록을 설정해야 하며, 와일드카드는 지원되지 않습니다.
작업이 계속 queued 상태
먼저 워커 로그를 확인하세요. docker-compose logs -f worker에 오류가 있으면 문제가 노출됩니다. 그런 다음 curl -f http://localhost:8000/health/worker로 워커 하트비트를 확인하고, 503을 반환하면 워커가 연결이 끊겼거나 Redis에 연결할 수 없는 것입니다. ARQ 하트비트는 약 31초마다 만료됩니다.
전사가 30%에서 멈춤
이 단계는 AssemblyAI를 호출합니다. 백엔드 로그로 API 키가 유효한지, 계정 할당량이 충분한지 확인하세요. 상태 폴링에는 기본 900초의 전체 타임아웃 예산이 있으며, 시간 초과 시 동일한 전사 작업을 재시도하며 중복 청구되지 않습니다. 긴 비디오는 ASSEMBLY_AI_HTTP_TIMEOUT_SECONDS를 적절히 늘릴 수 있습니다.
클립 선택 모델 오류 또는 잘못된 출력 형식
LLM 접두사와 공급자 키가 일치해야 합니다: ollama:는 OLLAMA_BASE_URL 및 OLLAMA_API_KEY와, google-gla:는 GOOGLE_API_KEY와, 등등. 로컬 모델이 비정상적인 구조의 JSON을 반환하면 에이전트는 최대 두 번 재시도합니다(output_retries=2). 지시사항 준수 능력이 더 강한 모델로 바꾸는 것이 일반적으로 해결책입니다.
계정 등록 시 Failed to create account 오류
대부분 데이터베이스 스키마가 코드보다 오래된 것입니다. 멱등 수리 스크립트를 한 번 실행하세요. 열만 추가하고 기존 데이터는 건드리지 않습니다.
docker compose exec -T postgres psql -U supoclip -d supoclip < scripts/selfhost-schema-repair.sql
이 데이터베이스에 prisma db push나 prisma migrate deploy를 절대 실행하지 마세요. 백엔드가 Prisma가 모르는 테이블을 직접 관리하며, db push는 그 테이블을 삭제합니다.
추가 자료 / 고급 방향
- 완전 로컬 경로:
TRANSCRIPTION_PROVIDER를whisper로 바꾸고, 클립 선택은LLM=ollama:...과 로컬 Ollama 서비스를 사용하세요. Docker의 기본 Ollama 주소는http://host.docker.internal:11434/v1이며, 호스트의 Ollama가 해당 포트를 수신해야 합니다. - MCP 통합: 저장소의
mcp/디렉터리는 MCP 서버를 제공하므로 Claude, Cursor 등의 클라이언트에서 SupoClip의 편집 기능을 직접 호출할 수 있습니다. - REST API:
/settings/api-keys에서 API 키를 생성하고 백엔드 API를 직접 호출하여 스크립트 기반 일괄 처리에 적합합니다. - B-roll 자산:
PEXELS_API_KEY를 설정하면 AI가 클립을 선택한 후 Pexels 무료 스톡 비디오를 자동으로 매칭하여 보조 영상으로 사용합니다. - 라이선스 경계: 현재 버전은 SupoClip Noncommercial Source License 1.1로, 비상업적 용도 및 개인 크리에이터의 셀프미디어 수익화는 무료이며, 회사, 기관, 팀 또는 대행 편집 서비스는 서면 허가를 이메일로 요청해야 합니다. 시작하기 전에
LICENSE파일, 특히 "Individual Creators" 정의를 읽어보세요.