PeakCut 실전: 나만의 AI 숏폼 영상 편집 도구 만들기
숏폼 영상을 만들 때 가장 시간이 많이 걸리는 작업은 편집이 아니라, 한두 시간 분량의 라이브나 긴 영상에서 게시할 가치가 있는 수십 초를 찾아내는 일입니다. PeakCut은 이 파이프라인을 자동화합니다: 로컬에서 음성 인식을 실행하고, AI가 하이라이트 장면을 골라주며, 자동으로 9:16 세로 화면으로 자르고 자막을 입힙니다. 가장 매력적인 점은 전체 과정이 전적으로 내 컴퓨터에서 실행되어 비디오와 오디오 데이터가 내 기기를 벗어나지 않는다는 것입니다.
작업 흐름은 매우 직관적입니다: 오디오를 전사하고, AI가 낯선 사람의 주의를 끌 수 있는 장면을 판단하고, FFmpeg로 자막이 포함된 세로 화면 영상을 렌더링합니다. 전사에는 sherpa-onnx와 Parakeet 모델을 사용하며 완전히 로컬에서 실행됩니다; AI는 장면 선택과 제목 작성을 담당하며, 어떤 제공업체를 사용하든 상관없습니다. OpenAI 호환 API라면 모두 연결할 수 있습니다.
공식 ChatGPT API를 사용하고 싶지 않다면, Defapi가 좋은 선택입니다. 가격은 공식의 절반이며, 모든 모델이 기본적으로 v1/chat/completions, v1/messages, v1beta/models/ 같은 주요 프로토콜과 호환되므로, PeakCut의 Custom provider로 바로 연결할 수 있으며 설정 방법은 아래 3단계와 동일합니다.
핵심 의존성 및 환경
시작하기 전에 다음 항목을 확인하세요:
- Python 3.10+: 메인 프로그램 실행 환경.
- FFmpeg: 모든 비디오 및 오디오 처리는 이것에 의존합니다. Windows:
winget install Gyan.FFmpeg, macOS:brew install ffmpeg, Linux:sudo apt install ffmpeg. - 네트워크 및 저장 공간: 첫 실행 시 약 480MB의 음성 모델을 다운로드합니다. 비디오 파일 자체가 작지 않으므로 20GB 이상의 디스크 공간을 권장합니다.
- AI Key (선택): 설정하지 않아도 사용할 수 있으며, 이 경우 PeakCut은 볼륨에 따라 장면을 선택하지만 AI 생성 제목은 없습니다.
PeakCut은 프로젝트를 고정된 경로에 두는 것을 권장합니다. 예: C:\peakcut (Windows) 또는 ~/peakcut (macOS/Linux). 임시 디렉토리에 두지 마세요. Windows에서 경로가 너무 깊으면 음성 모델 로딩에 실패할 수 있습니다.
프로젝트 구조 트리
peakcut/
├── studio/ # 서버 측 메인 코드
│ ├── server.py # FastAPI 엔트리 포인트
│ ├── ai.py # AI 서비스 어댑터 계층 (새 provider는 여기에 추가)
│ ├── transcribe.py # 로컬 음성 전사
│ ├── jobs.py # 편집 작업 파이프라인
│ ├── render.py # 자막 렌더링 및 비디오 합성
│ └── fonts/ # 자막 폰트 파일
├── web/ # 프론트엔드 페이지 (순수 HTML/CSS/JS)
├── deploy/ # Docker 배포 설정
├── tests/ # 자동화 테스트
├── requirements.txt # Python 의존성
├── .env.example # 환경 변수 템플릿
└── Dockerfile
단계별 가이드
1. 저장소 클론 및 의존성 설치
git clone https://github.com/haziqahmedqasmi/peakcut.git ~/peakcut
cd ~/peakcut
pip install -r requirements.txt
가상 환경 사용을 권장합니다. 전역 Python 패키지를 오염시키지 않도록.
2. 로컬 서비스 시작
python -m studio.server
첫 시작 시 음성 모델(약 480MB)이 자동으로 다운로드되며 시간이 걸립니다. Uvicorn running on http://127.0.0.1:8765 같은 출력이 보이면 서비스가 실행된 것입니다.
브라우저에서 http://127.0.0.1:8765를 열면 로그인 없이 콘솔에 바로 들어갑니다.
3. AI 서비스 설정
설정 → AI 페이지로 이동합니다. 여기서 사용할 AI 서비스 제공업체를 선택합니다. PeakCut의 AI는 두 가지 작업을 담당합니다: 어떤 장면을 편집할 가치가 있는지 결정하고, 장면에 제목을 생성합니다. JSON을 반환할 수 있는 채팅 모델이 필요하며, 음성 전사 서비스는 아닙니다—전사는 항상 로컬에서 실행됩니다.
드롭다운에서 **Custom (OpenAI-compatible)**을 선택하면 Base URL 입력 필드가 나타납니다. 서비스 제공업체 주소를 입력하고, Key 필드에 API 키를 붙여넣고, 모델 ID에 JSON 출력을 지원하는 채팅 모델 이름을 수동으로 입력한 후 Find models를 클릭하여 사용 가능한 모델 목록을 가져옵니다(서비스 제공업체가 지원하는 경우). 마지막으로 Save and test를 클릭합니다.
예를 들어, Defapi는 OpenAI 호환 API를 제공하며 가격이 공식의 절반입니다. 설정은 다음과 같습니다:
- Base URL:
https://api.defapi.org/v1 - Key: Defapi 플랫폼 콘솔에서 가져옵니다.
- 모델: JSON 출력을 지원하는 채팅 모델 ID를 입력합니다. 예:
your-model-id(정확한 ID는 계정 관리자 목록을 따르세요)
Defapi는 v1/chat/completions, v1/messages, v1beta/models/ 같은 주요 프로토콜과 호환되므로, PeakCut의 Custom provider로 직접 연결할 수 있습니다.
참고: 이전에 .env 파일을 통해 AI 매개변수를 구성한 경우, 콘솔에 저장된 구성이 .env의 설정을 덮어씁니다. .env를 사용하려면 해당 변수는 다음과 같습니다:
PEAKCUT_AI_PROVIDER=custom
PEAKCUT_AI_MODELS=your-model-id
PEAKCUT_AI_KEY=your-key
PEAKCUT_AI_BASE_URL=https://api.defapi.org/v1
4. 비디오 가져오기
홈페이지 상단에 붙여넣기 상자가 있으며, YouTube, Twitch, Kick 링크를 지원하고 로컬 비디오 파일을 직접 업로드할 수도 있습니다.
옵션에서 생성할 클립 수(1-20개), 최소/최대 길이(최소 5초, 최대 180초), 자막 스타일(Bounce/Hype/Clean), 화면 레이아웃(흐림 채우기/확대/크롭/게임 화면+카메라), 해상도(720p/1080p)를 설정할 수 있고, 비디오의 특정 부분만 처리하도록 제한할 수도 있습니다.
자막 생성이라는 옵션이 있으며 기본적으로 켜져 있습니다. 자막은 단어별로 강조되며, 음성 모델이 타임스탬프가 포함된 인식 결과를 출력해야 합니다. 기본 모델은 영어에 가장 최적화되어 있습니다. 다른 언어를 사용하려면 모델을 교체해야 하며, 이에 대한 자세한 내용은 문제 해결 섹션에서 설명합니다.
링크를 입력하고 Make clips를 클릭하여 처리를 시작합니다.
5. 클립 필터링 및 자막 조정
처리 완료 후 비디오 세부 정보 페이지로 이동하면 생성된 모든 클립을 볼 수 있습니다. 각 클립에서 다음을 수행할 수 있습니다:
- 미리보기: 결과가 만족스러운지 확인
- 시작/끝 지점 조정: 타임라인을 드래그하여 미세 조정
- 자막 수정: 인식 오류가 있으면 단어를 수동으로 변경
- 자막 스타일 변경: 세 가지 스타일을 자유롭게 전환
PeakCut은 각 클립에 대해 커버 이미지와 매력적인 제목(AI 생성)을 생성합니다. 제목이 마음에 들지 않으면 직접 수정할 수 있습니다.
6. 세로 화면 클립 내보내기
클립에 문제가 없으면 Download를 클릭하여 내보냅니다. 렌더링은 FFmpeg로 완료되며, 최종 출력은 9:16 세로 형식이고 자막이 화면에 표시됩니다.
YouTube, Instagram 또는 TikTok 계정 연결을 구성했다면 여기서 직접 게시할 수도 있습니다. 단일 머신 사용 시 먼저 다운로드한 다음 수동으로 업로드하는 것이 좋습니다.
일반적인 문제 해결
FFmpeg 누락
시작 후 콘솔에 FFmpeg를 찾을 수 없다는 메시지가 표시됩니다. ffmpeg -version이 정상적으로 출력되는지 확인하고, 그렇지 않으면 다시 설치하고 PATH에 있는지 확인하세요.
음성 모델 다운로드 실패
첫 시작 시 모델 다운로드가 중단되면 data/models/ 디렉토리에서 해당 폴더를 삭제하고 서비스를 재시작하여 다시 다운로드하게 합니다. 네트워크가 불안정하면 Hugging Face에서 수동으로 다운로드하여 지정된 디렉토리에 배치할 수 있습니다.
콘솔에서 설정한 AI가 적용되지 않음
설정 → AI 페이지에 구성이 저장되었는지 확인하세요. 콘솔에 저장된 구성은 .env 파일보다 우선합니다. 이전에 .env에 AI 관련 변수를 작성한 경우, 콘솔에서 한 번 저장하면 .env는 무시됩니다. .env 구성으로 돌아가려면 콘솔에서 provider를 다시 선택하고 저장해야 합니다.
AI가 JSON 형식 오류 반환
모델 ID가 JSON 출력을 지원하는 채팅 모델인지 확인하세요. 일부 모델(특히 순수 추론 모델)은 유효한 JSON 반환을 보장하지 않습니다. 다른 모델로 시도하세요. AI usage 페이지에서 자세한 요청 로그를 볼 수도 있습니다.
자막 언어가 잘못됨
기본 Parakeet 모델은 영어만 지원합니다. 중국어 영상의 경우 중국어를 지원하는 sherpa-onnx 모델로 교체하거나(studio/config.py의 ASR_MODEL_NAME 변경), YouTube 자체 중국어 전사를 사용하십시오(이 기능은 기본적으로 활성화되어 있으며 YouTube 전사 텍스트가 우선 사용됩니다).
디스크 공간 부족
data/ 디렉토리에 모든 비디오와 생성 결과가 저장됩니다. 긴 비디오를 처리하기 전에 디스크 공간을 확인하세요. 설정 → Storage에서 현재 저장 경로와 남은 공간을 볼 수 있으며, 데이터 디렉토리를 다른 디스크로 이동할 수도 있습니다.
추가 자료 / 고급 방향
PeakCut은 이미 녹화된 비디오를 편집할 수 있을 뿐만 아니라 라이브 스트리밍 중에 실시간으로 녹화하고 하이라이트 장면을 편집할 수도 있습니다. 각 크리에이터에 대해 workspace를 만들고 채널을 설정하면 자동으로 감시하고, 라이브 중에 클립을 생성합니다.
여러 사용자와 협업하거나 공개 배포하려면 DEPLOY.md를 참조하십시오: Docker로 앱 + PostgreSQL + Caddy로 자동 HTTPS를 실행하고, 이메일 가입 및 Google 로그인을 지원합니다. 공개 배포 시 반드시 PEAKCUT_ACCOUNTS=1을 활성화하십시오. 그렇지 않으면 주소를 아는 사람 누구나 AI 키를 사용할 수 있습니다.
소셜 미디어 계정(YouTube/Instagram/TikTok)을 연결하려면 각 플랫폼에서 개발자 애플리케이션을 등록해야 합니다. 플랫폼 검토 기간 동안 업로드된 비디오는 기본적으로 비공개 상태이며, 이는 플랫폼의 제한이지 PeakCut 자체 문제가 아닙니다.
더 깊이 파고들고 싶다면, studio/ai.py는 AI 서비스와 상호작용하는 유일한 파일이며, 새 provider를 추가하거나 요청 로직을 디버깅할 때 여기서 시작합니다. 코드에는 테스트 스위트(python tests/run.py)도 포함되어 있어, 코드를 수정한 후 실행하면 회귀를 방지할 수 있습니다.