설명
짧은 형식의 비디오 콘텐츠를 제작하는 오픈소스 자동 비디오 제작 도구입니다. Short Video Maker는 텍스트 음성 변환, 자동 자막, 배경 영상, 음악을 결합하여 간단한 텍스트 입력만으로 매력적인 짧은 비디오를 제작합니다.
이 프로젝트는 GPU 성능을 많이 소모하는 비디오 생성(그리고 값비싼 타사 API 호출)에 대한 무료 대안을 제공하기 위한 것입니다. 이미지나 이미지 프롬프트를 기반으로 비디오를 처음부터 생성하지 않습니다.
이 저장소는 AI Agents AZ 유튜브 채널 에서 오픈소스로 공개되었습니다. 더 많은 AI 관련 콘텐츠와 튜토리얼을 보시려면 해당 채널을 방문해 보세요.
서버는 MCP 와 REST 서버를 제공합니다.
MCP 서버는 AI 에이전트(예: n8n)와 함께 사용할 수 있지만 REST 엔드포인트는 비디오 생성에 더 많은 유연성을 제공합니다.
REST/MCP 서버로 생성된 n8n 워크플로의 예를 이 저장소에서 찾을 수 있습니다.
목차
시작하기
용법
정보
n8n 튜토리얼
예시
특징
- 텍스트 프롬프트에서 완전한 짧은 비디오를 생성합니다.
- 텍스트-음성 변환
- 자동 캡션 생성 및 스타일링
- Pexels를 통한 배경 비디오 검색 및 선택
- 장르/분위기 선택이 가능한 배경음악
- REST API와 MCP(Model Context Protocol) 서버 역할을 모두 수행합니다.
작동 원리
Shorts Creator는 간단한 텍스트 입력과 검색어를 받아 다음을 수행합니다.
- Kokoro TTS를 사용하여 텍스트를 음성으로 변환합니다
- Whisper를 통해 정확한 캡션을 생성합니다.
- Pexels에서 관련 배경 비디오를 찾습니다.
- 모든 요소를 Remotion으로 구성합니다.
- 완벽한 타이밍의 자막으로 전문적인 짧은 영상을 렌더링합니다.
제한 사항
- 이 프로젝트는 영어 음성 해설이 포함된 비디오만 생성할 수 있습니다(kokoro-js는 현재 다른 언어를 지원하지 않습니다)
- 배경 영상은 Pexels에서 가져왔습니다.
일반 요구 사항
- 인터넷
- 무료 Pexels API 키
- ≥ 3GB 여유 RAM, 권장 사항은 4GB RAM입니다.
- ≥ 2 vCPU
- ≥ 5GB 디스크 공간
국립민간공원
Docker를 사용하여 프로젝트를 실행하는 것이 권장되지만, npm이나 npx를 사용하여 실행할 수도 있습니다. 일반적인 요구 사항 외에도 서버를 실행하려면 다음 사항이 필요합니다.
지원되는 플랫폼
- Ubuntu ≥ 22.04(Whisper.cpp용 libc 2.5)
- 필수 패키지:
git wget cmake ffmpeg curl make libsdl2-dev libnss3 libdbus-1-3 libatk1.0-0 libgbm-dev libasound2 libxrandr2 libxkbcommon-dev libxfixes3 libxcomposite1 libxdamage1 libatk-bridge2.0-0 libpango-1.0-0 libcairo2 libcups2
- 필수 패키지:
- 맥 OS
- ffmpeg (
brew install ffmpeg
) - node.js (22+에서 테스트됨)
- ffmpeg (
현재 Windows는 지원되지 않습니다 (whisper.cpp 설치가 가끔 실패합니다).
개념
장면
각 비디오는 여러 장면으로 구성됩니다. 이러한 장면은 다음과 같습니다.
- 텍스트: 내레이션, TTS가 읽고 자막을 생성할 텍스트입니다.
- 검색어: 서버가 Pexels API에서 비디오를 찾는 데 사용해야 하는 키워드입니다. 키워드를 찾을 수 없는 경우, 조커 용어(
nature
,globe
,space
,ocean
)를 사용합니다.
시작하기
Docker(권장)
세 가지 사용 사례에 맞는 세 가지 도커 이미지가 있습니다. 일반적으로는 tiny
이미지를 사용하는 것이 좋습니다.
매우 작은
tiny.en
whipper.cpp 모델을 사용합니다.q4
양자화된 kokoro 모델을 사용합니다.- 제한된 리소스로 Remotion에서 발생하는 OOM 오류를 극복하기 위해
CONCURRENCY=1
사용합니다. - 제한된 리소스로 Remotion에서 발생하는 OOM 오류를 극복하기 위해
VIDEO_CACHE_SIZE_IN_BYTES=104857600
(100mb)
지엑스피1
정상
base.en
whipper.cpp 모델을 사용합니다.fp32
kokoro 모델을 사용합니다- 제한된 리소스로 Remotion에서 발생하는 OOM 오류를 극복하기 위해
CONCURRENCY=1
사용합니다. - 제한된 리소스로 Remotion에서 발생하는 OOM 오류를 극복하기 위해
VIDEO_CACHE_SIZE_IN_BYTES=104857600
(100mb)
쿠다
Nvidia GPU를 소유하고 있고 GPU 가속 기능을 갖춘 더 큰 소형 모델을 사용하려는 경우 CUDA 최적화된 Docker 이미지를 사용할 수 있습니다.
- GPU 가속을 사용한
medium.en
whipper.cpp 모델을 사용합니다. fp32
kokoro 모델을 사용합니다- 제한된 리소스로 Remotion에서 발생하는 OOM 오류를 극복하기 위해
CONCURRENCY=1
사용합니다. - 제한된 리소스로 Remotion에서 발생하는 OOM 오류를 극복하기 위해
VIDEO_CACHE_SIZE_IN_BYTES=104857600
(100mb)
도커 컴포즈
Docker Compose를 사용하여 n8n이나 다른 서비스를 실행하고 이를 결합하고 싶을 수 있습니다. 서비스 구성에 공유 네트워크를 추가해야 합니다.
자체 호스팅 AI 스타터 키트를 사용하는 경우 ** short-video-maker
서비스**에 networks: ['demo']
추가해야 n8n에서 http://short-video-maker:3123을 통해 해당 서비스에 접속할 수 있습니다.
웹 UI
@mushitori는 브라우저에서 비디오를 생성하는 웹 UI를 만들었습니다.
http://localhost:3123 에서 로드할 수 있습니다.
환경 변수
🟢 구성
열쇠 | 설명 | 기본 |
---|---|---|
PEXELS_API_KEY | (무료) Pexels API 키 | |
로그 레벨 | 피노 로그 레벨 | 정보 |
WHISPER_VERBOSE | Whisper.cpp의 출력을 stdout으로 전달해야 하는지 여부 | 거짓 |
포트 | 서버가 수신할 포트 | 3123 |
⚙️ 시스템 구성
열쇠 | 설명 | 기본 |
---|---|---|
코코로_모델_정밀도 | 사용할 Kokoro 모델의 크기입니다. 유효한 옵션은 fp32 , fp16 , q8 , q4 , q4f16 입니다. | 상황에 따라 다르겠지만, 위의 도커 이미지 설명을 참조하세요 ^^ |
동시성 | 동시성은 렌더링 중에 동시에 열리는 브라우저 탭의 수를 나타냅니다. 각 Chrome 탭은 웹 콘텐츠를 렌더링한 후 스크린샷을 찍습니다. 이 값을 조정하면 제한된 리소스로 프로젝트를 실행하는 데 도움이 됩니다. | 상황에 따라 다르겠지만, 위의 도커 이미지 설명을 참조하세요 ^^ |
비디오 캐시 크기(바이트) | 캐시용 Remotion의 프레임입니다. 이 값을 조정하면 제한된 리소스로 프로젝트를 실행하는 데 도움이 됩니다. | 상황에 따라 다르겠지만, 위의 도커 이미지 설명을 참조하세요 ^^ |
⚠️ 위험 구역
열쇠 | 설명 | 기본 |
---|---|---|
위스퍼_모델 | 어떤 whipping.cpp 모델을 사용해야 할까요? 유효한 옵션은 tiny , tiny.en , base , base.en , small , small.en , medium , medium.en , large-v1 , large-v2 , large-v3 , large-v3-turbo 입니다. | 경우에 따라 다릅니다. 위의 도커 이미지 설명을 참조하세요. npm의 경우 기본 옵션은 medium.en 입니다. |
데이터 디렉토리 경로 | 프로젝트의 데이터 디렉토리 | npm과 Docker 이미지의 /app/data 사용하여 ~/.ai-agents-az-video-generator |
도커 | 프로젝트가 Docker 컨테이너에서 실행되는지 여부 | docker 이미지의 경우 true , 그렇지 않으면 false |
개발자 | 추측하다! :) | false |
구성 옵션
열쇠 | 설명 | 기본 |
---|---|---|
패딩백 | 내레이션이 끝난 후 비디오를 얼마나 오랫동안 재생해야 하는지를 나타내는 끝 화면(밀리초 단위). | 0 |
음악 | 배경 음악의 분위기입니다. GET /api/music-tags 엔드포인트에서 사용 가능한 옵션을 확인하세요. | 무작위의 |
캡션위치 | 캡션을 렌더링할 위치입니다. 가능한 옵션: top , center , bottom . 기본값 | bottom |
캡션배경색 | 활성 캡션 항목의 배경색입니다. | blue |
목소리 | 코코로 목소리. | af_heart |
정위 | 비디오 방향입니다. portrait 및 landscape 옵션이 있습니다. | portrait |
음악 볼륨 | 배경 음악의 볼륨을 설정합니다. 가능한 옵션은 low medium high , muted 입니다. | high |
용법
MCP 서버
서버 URL
/mcp/sse
/mcp/messages
사용 가능한 도구
create-short-video
짧은 비디오를 생성합니다. LLM이 적절한 구성을 찾아냅니다. 특정 구성을 사용하려면 프롬프트에서 해당 구성을 지정해야 합니다.get-video-status
별로 쓸모가 없습니다. 비디오 상태를 확인하기 위한 용도인데, AI 에이전트가 시간 개념에 능숙하지 않기 때문에 결국 REST API를 사용하게 될 가능성이 큽니다.
REST API
GET /health
Healthcheck 엔드포인트
POST /api/short-video
GET /api/short-video/{id}/status
GET /api/short-video/{id}
응답: 비디오의 이진 데이터.
/api/short-videos
가져오세요
/api/short-video/{id}
삭제
GET /api/voices
GET /api/music-tags
문제 해결
도커
서버에는 최소 3GB의 여유 메모리가 필요합니다. Docker에 충분한 RAM을 할당하세요.
Windows에서 wsl2를 통해 서버를 실행하는 경우 wsl 유틸리티 2 에서 리소스 제한을 설정해야 합니다. 그렇지 않은 경우 Docker Desktop에서 설정하세요. (Ubuntu는 run 명령으로 지정하지 않는 한 리소스를 제한하지 않습니다.)
국립민간공원
필요한 패키지가 모두 설치되어 있는지 확인하세요.
엔8엔
MCP(또는 REST) 서버 설정은 n8n과 서버를 실행하는 방식에 따라 달라집니다. 아래 표의 예시를 참고해 주세요.
|n8n은 n8n start
사용하여 로컬로 실행 중입니다.|n8n은 Docker를 사용하여 로컬로 실행됩니다.|n8n은 클라우드에서 실행됩니다|
|---|---|---|---|
|short-video-maker
Docker에서 로컬로 실행됩니다.|http://localhost:3123
|경우에 따라 다릅니다. 기술적으로는 http://host.docker.internal:3123
사용할 수 있습니다. 이는 호스트를 가리키기 때문입니다. 하지만 동일한 네트워크를 사용하고 http://short-video-maker:3123
처럼 서비스 이름을 사용하여 통신하도록 설정할 수도 있습니다.|작동하지 않습니다 - 클라우드에 short-video-maker
배포|
|short-video-maker
npm/npx로 실행됩니다.|http://localhost:3123
|http://host.docker.internal:3123
|작동하지 않습니다 - 클라우드에 short-video-maker
배포|
|short-video-maker
클라우드에서 실행됩니다.|귀하의 IP 주소 http://{YOUR_IP}:3123
사용해야 합니다.|귀하의 IP 주소 http://{YOUR_IP}:3123
사용해야 합니다.|귀하의 IP 주소 http://{YOUR_IP}:3123
사용해야 합니다.|
클라우드에 배포
각 VPS 제공업체는 다르고 모든 제공업체에 구성을 제공하는 것은 불가능하지만, 다음과 같은 몇 가지 팁을 알려드리겠습니다.
- Ubuntu ≥ 22.04를 사용하세요
- ≥ 4GB RAM, ≥ 2vCPU 및 ≥5GB 스토리지를 보유합니다.
- pm2를 사용하여 서버를 실행/관리합니다.
- 환경 변수를
.bashrc
파일(또는 유사한 파일)에 넣으세요.
자주 묻는 질문
다른 언어를 사용할 수 있나요? (프랑스어, 독일어 등)
아쉽게도 현재로서는 불가능합니다. Kokoro-js는 영어만 지원합니다.
이미지와 비디오를 전달하고 이를 함께 연결할 수 있나요?
아니요
npm
이나 docker
로 프로젝트를 실행해야 할까요?
Docker는 프로젝트를 실행하는 데 권장되는 방법입니다.
비디오 생성에 얼마나 많은 GPU가 사용되나요?
솔직히 말해서, 별로 없어요. Whisper.cpp만 가속이 가능합니다.
Remotion은 CPU를 많이 사용하고, Kokoro-js는 CPU에서 실행됩니다.
비디오를 생성하는 데 사용할 수 있는 UI가 있나요?
아직 아님)
Pexels와 다른 비디오 소스를 선택할 수 있나요? 아니면 내 비디오를 직접 제공할 수 있나요?
아니요
이 프로젝트는 이미지로부터 비디오를 생성할 수 있나요?
아니요
비디오 생성에 대한 종속성
의존 | 버전 | 특허 | 목적 |
---|---|---|---|
감정 | ^4.0.286 | 모션 라이센스 | 비디오 구성 및 렌더링 |
위스퍼 CPP | v1.5.5 | MIT | 캡션을 위한 음성-텍스트 변환 |
FFmpeg | ^2.1.3 | LGPL/GPL | 오디오/비디오 조작 |
코코로.js | ^1.2.0 | MIT | 텍스트-음성 생성 |
펙셀 API | 해당 없음 | Pexels 이용 약관 | 배경 영상 |
어떻게 기여할 수 있나요?
PR을 환영합니다. 로컬 개발 환경 설정 방법은 CONTRIBUTING.md 파일을 참조하세요.
특허
이 프로젝트는 MIT 라이선스 에 따라 라이선스가 부여되었습니다.
감사의 말
Related MCP Servers
- Gozlib License
- PythonMIT License
- PythonMIT License
- TypeScriptMIT License