OpenShorts 배포 실전: 긴 영상을 AI 숏폼으로 바꾸기
팟캐스트, 라이브 또는 인터뷰 프로그램을 만드는 사람이라면 누구나 이런痛点이 있습니다: 한 시간짜리 영상에서 진짜 숏폼으로 적합한 하이라이트 순간은 단 몇 분뿐입니다. 수동으로 다시 보고, 편집하고, 자막을 넣고, 재구성하는 전체 과정은 반나절이 걸립니다. OpenShorts는 오픈소스 OpusClip 대안으로, 이 파이프라인을 자동화합니다—긴 영상을 넣으면 자동으로 전사하고, AI가 하이라이트 클립을 선택하고, 9:16 세로 화면으로 재구성하고, 자막을 구워 넣어, 마지막에 바로 게시할 수 있는 완성본을 출력합니다.
작동 원리를 살펴봅시다: 먼저 faster-whisper로 오디오에 대해 단어 수준 타임스탬프 전사를 수행하고, PySceneDetect로 장면 경계를 식별합니다. 그런 다음 Gemini 또는 OpenAI 호환 로컬 모델로 전사 텍스트에 점수를 매겨 15-60초 길이의 하이라이트 순간 3-15개를 선택합니다. 각 클립은 지능적으로 재구성됩니다—두 사람 대화 시 상하로 겹치고, 한 사람일 때 얼굴 추적 크롭이 적용되며, 자막은 화면 접합부에 구워집니다. 전체 프로세스는 Docker Compose로 오케스트레이션되며 자체 호스팅은 완전 무료이고 워터마크가 없습니다.
핵심 의존성 및 환경
시작하기 전에 기계가 다음 조건을 충족하는지 확인하세요:
- Docker와 Docker Compose: 배포의 유일한 의존성으로, 호스트에 Python이나 Node를 설치할 필요가 없습니다.
- 메모리: 8GB 이상, 모델 추론과 비디오 인코딩 모두 메모리를 많이 사용합니다.
- 저장 공간: 비디오 파일 자체와 전사 및 렌더링 중간 산출물, 최소 20GB 이상을 권장합니다.
- 네트워크: Docker 이미지를 가져오고 모델(HuggingFace, Ultralytics)을 다운로드할 수 있어야 합니다.
- CPU가 기본 경로이며, NVIDIA GPU 선택적 가속은 나중에 설명합니다.
AI 서비스의 역할을 미리 명확히 해야 합니다:
| 서비스 | 용도 | 필수 여부 |
|---|---|---|
| Gemini 또는 OpenAI 호환 LLM | 텍스트 하이라이트 선택, 스크립트 생성, 제목 | 최소 하나 선택 |
| Gemini(비전) | 자동 레이아웃 선택, 화면 표시 내용 인식, 무음 비디오 | 선택적 |
| fal.ai | AI 배우 생성, 디지털 휴먼 비디오, 입술 동기화 | AI Shorts 기능에만 필요 |
| ElevenLabs | 더빙, 다국어 클로닝 | 선택적 |
| Upload-Post | 다중 플랫폼 자동 게시 | 선택적 |
메인 기능은 v1/chat/completions를 호출할 수 있는 텍스트 모델 하나만 필요하며, Gemini 비전, fal.ai, ElevenLabs는 핵심 클립 파이프라인에 영향을 주지 않습니다.
프로젝트 구조 트리
openshorts/
├── app.py # FastAPI 백엔드 진입점
├── main.py # 핵심 파이프라인: 전사, 하이라이트 감지, 클립
├── llm_backend.py # OpenAI 호환 LLM 어댑터 레이어(핵심 파일)
├── gemini_worker.py # Gemini 호출 및 JSON 파싱
├── layout_picker.py # 자동 레이아웃 선택
├── s3_uploader.py # S3 스토리지(선택적)
├── render-service/ # Remotion 렌더링 서비스
│ └── Dockerfile
├── dashboard/ # React 프론트엔드(Vite + Tailwind)
│ ├── src/
│ └── package.json
├── docker-compose.yml # 3개 서비스 오케스트레이션
├── .env.example # 환경 변수 템플릿
└── Dockerfile # CPU/GPU 멀티 스테이지 빌드
세 가지 핵심 서비스: backend(FastAPI, 포트 8000), frontend(Vite 개발 서버, 5175로 매핑), renderer(Remotion 렌더링, 포트 3100).
단계별 배포 가이드
1. 저장소 클론
git clone https://github.com/mutonby/openshorts.git
cd openshorts
2. AI 서비스 구성
먼저 환경 변수 템플릿을 복사하세요:
cp .env.example .env
.env를 열고 LLM_BASE_URL 관련 구성을 찾으세요. 이것이 텍스트 하이라이트 선택 서비스를 연결하는 곳입니다. OpenShorts의 llm_backend.py는 LLM_BASE_URL에 /chat/completions 경로를 추가하며, OpenAI 프로토콜 형식과 완전히 호환됩니다. Google Gemini를 사용하지 않으려면 텍스트 선택 부분을 호환되는 LLM 서비스로 지정할 수 있습니다.
비용을 절약하는 방법이 있습니다: Defapi 플랫폼 가격은 공식 채널의 절반이며, 웹사이트는 Defapi 입니다. 이 플랫폼의 모든 모델은 기본적으로 v1/chat/completions, v1/messages 및 v1beta/models/ 프로토콜과 호환되므로 OpenShorts를 직접 연결할 수 있습니다. 구성 방법은 다음과 같습니다:
LLM_BASE_URL=https://api.defapi.org/v1
LLM_MODEL=your-model-id # Defapi에서 사용하는 실제 모델 ID로 교체
LLM_API_KEY=your_defapi_key
이 진입점은 텍스트 전사의 하이라이트 점수와 상세 선택만 담당하며, Gemini의 비전 기능(자동 레이아웃, 무음 비디오 인식)을 대체하지 않고, fal.ai 비디오 생성이나 ElevenLabs 음성과도 관련이 없습니다. 메인 클립 파이프라인은 AI 배우, 소셜 게시 또는 클라우드 Autopilot에 의존하지 않으며, 이들은 추가 기능입니다. Defapi의 모든 모델은 기본적으로 v1/chat/completions, v1/messages 및 v1beta/models/ 프로토콜과 호환되므로 전환 시 추가 적응 비용이 없습니다.
구성 후 /api/config 엔드포인트는 localLlm 정보를 반환하며, 프론트엔드 오른쪽 상단에서 더 이상 Gemini Key를 강제로 요구하지 않습니다. 참고: LLM_PROVIDER=gemini도 함께 구성하면 강제로 Gemini 경로를 사용하므로 해당 줄을 주석 처리하거나 삭제하세요.
3. 서비스 시작
docker compose up --build
첫 번째 빌드는 Python 3.11, Node 22, Deno 등 기본 이미지를 가져오고 Python 의존성과 프론트엔드 npm 패키지 설치가 필요하므로 시간은 네트워크에 따라 다릅니다. 빌드가 완료되면 백엔드, 프론트엔드, 렌더링 서비스가 순서대로 시작됩니다.
4. 비디오 업로드하여 하이라이트 생성
브라우저에서 http://localhost:5175에 접속하여 Dashboard로 들어가세요. 먼저 Settings에 API Key를 입력하세요(로컬 LLM을 구성한 경우 Gemini Key는 비워 둘 수 있습니다). 그런 다음:
- Clip Generator 클릭
- 유성 비디오 업로드 또는 YouTube 링크 붙여넣기
- 전사 및 선택 완료를 기다립니다(8분 비디오는 CPU에서 약 5-8분 소요).
완료 후 각 하이라이트 클립이 바이럴 점수, 플랫폼 제목 제안 및 편집 가능한 클립 트랙과 함께 인터페이스에 표시됩니다.
5. 자막 및 구성 편집
각 클립에는 완전한 클립 편집기가 내장되어 있습니다: 왼쪽 소스 모니터, 오른쪽 프로그램 모니터, 아래 전체 전사. 원하는 단어를 클릭하여 컷 포인트를 설정하고, 추가 클립을 추가하고, 구성 모드를 전환할 수 있습니다(단일 인물 추적, 이중 인물 상하 분할, 세로 블러 배경, 화면 녹화). 변경 후 재렌더링을 클릭하면 몇 초 안에 결과물이 나옵니다.
6. 완성본 내보내기
확인 후 내보내기를 클릭하세요. 렌더링 서비스는 FFmpeg를 호출하여 자막, 후크 문구, 화면 비율 변환을 최종 파일에 구워 넣고 ./output 디렉토리로 출력합니다. 내보낸 것은 TikTok, YouTube Shorts 또는 Instagram Reels에 직접 게시할 수 있는 9:16 세로 비디오입니다.
일반적인 문제 해결
이미지 빌드 실패 또는 모델 다운로드 시간 초과
국내 네트워크 환경에서 HuggingFace 모델(whisper, YOLO) 또는 Docker 이미지 가져오기가 자주 중단됩니다. 미러 가속기를 구성하고 Docker 데몬에 프록시를 설정하세요. 모델 다운로드 실패 시 컨테이너 볼륨을 삭제하고 다시 시도하세요:
docker compose down -v
docker compose up --build
LLM_BASE_URL을 구성했지만 여전히 Gemini Key 요청
.env에 LLM_PROVIDER=gemini가 있는지 확인하고 있으면 삭제하세요. 또한 LLM_BASE_URL 끝에 불필요한 슬래시가 없는지 확인하세요. llm_backend.py가 경로를 직접 연결합니다.
로컬 모델이 유효한 JSON을 반환하지 않음
OpenShorts는 세 가지 response_format 전략을 순서대로 시도합니다: json_schema → json_object → 제한 없음. 7B 이상 모델은 일반적으로 안정적으로 반환하지만 3B 모델은 실패하기 쉽습니다. JSON 파싱 오류가 자주 발생하면 더 큰 모델을 사용하거나 LLM_SCORE_BATCH(기본 3)를 낮춰 단일 요청의 컨텍스트 양을 줄이세요.
Dashboard는 열리지만 백엔드 API 502
세 서비스 간 의존성이 있어 프론트엔드가 백엔드보다 먼저 시작됩니다. 백엔드 로그에 Uvicorn running이 나타난 후 페이지를 새로 고치세요. 지속적으로 502가 발생하면 백엔드 컨테이너를 확인하세요:
docker logs openshorts-backend
Gemini Key가 없을 때 기능 누락
로컬 LLM을 구성하면 텍스트 선택은 정상이지만 다음 기능이 저하됩니다: 자동 레이아웃 선택은 얼굴 추적 크롭으로 대체되고, 무음 비디오는 오류를 반환하며, 화면 표시 내용 인식은 꺼집니다. 이러한 기능을 사용하려면 Settings에 Gemini Key를 입력하세요. 두 경로를 병행할 수 있습니다—텍스트는 로컬 모델, 비전은 Gemini.
메모리 또는 디스크 부족
전사 및 렌더링은 모두 많은 리소스를 사용합니다. 8GB 메모리는 최소이고 16GB가 더 안정적입니다. 디스크 측면에서 whisper 모델은 약 3GB, YOLO 모델은 약 6MB이며, 비디오 파일과 중간 산출물을 포함하면 8분 비디오 전체 처리에 약 10GB 임시 공간이 필요합니다. 처리 후 output 디렉토리를 정리하세요.
확장 읽기 및 고급 방향
GPU 가속: 기본 CPU 이미지로 8분 비디오를 처리하는 데 5-8분이 걸리며, NVIDIA GPU(NVENC 지원 모델)가 있으면 1분으로 줄일 수 있습니다. README의 docker-compose.override.yml 구성을 참조하고, GPU: "1" 빌드 인자를 활성화하고 WHISPER_DEVICE=cuda 및 FFMPEG_ENCODER=auto를 설정하세요.
API 및 MCP 통합: OpenShorts는 완전한 REST API와 MCP 서버를 제공하며, Claude 또는 ChatGPT를 통해 자연어로 직접 작업할 수 있습니다: "이 팟캐스트를 TikTok용 클립 3개로 잘라줘". 자체 호스팅 시 Key 없이 서비스 시작 즉시 사용할 수 있습니다.
Google Key 없는 완전 로컬 실행: README는 상세한 로컬 LLM 구성 가이드를 제공합니다. 텍스트 선택 외에도 Ollama와 같은 도구를 구성하여 전체 파이프라인이 네트워크에 접촉하지 않도록 할 수 있습니다. 참고: Ollama는 OLLAMA_CONTEXT_LENGTH=16384를 설정해야 하며, 그렇지 않으면 기본 4096 컨텍스트가 조용히 잘려 JSON이 불완전해집니다.
라이선스 참고 사항: 핵심 앱은 MIT 라이선스로 완전히 자유롭습니다. 하지만 cloud/ 디렉토리의 코드(청구, 호스팅 인프라)는 OpenShorts Commercial License를 사용하며 개인 또는 내부적으로 사용할 수 있지만, 제3자에게 유료 호스팅 서비스로 제공할 수 없습니다. 자체 호스팅 핵심 기능에는 이 디렉토리가 필요 없습니다. 클라우드 버전(openshorts.app)과 자체 호스팅의 기능 차이는 주로 Autopilot(새 비디오 자동 클립)과 자동 게시(플랫폼 원클릭 연결)에 있으며, 자체 호스팅에서는 Upload-Post를 직접 구성하여 구현해야 합니다.