Revideo CLI 로컬 개발

Revideo CLI로 로컬에서 빠르게 영상을 렌더하고 디버깅하는 워크플로우를 다룬다. 서버 배포 전에 개발자가 반복해서 돌려보는 단계의 도구 모음이다.

🛠️ CLI 설치

@revideo/cli는 보통 프로젝트 devDependency로 함께 설치된다:

# 새 프로젝트 템플릿 (Revideo 공식 템플릿)
npm create @revideo/app@latest my-video
cd my-video
npm install

설치 후 다음 명령이 사용 가능해진다:

명령	용도
`npm start`	Studio/플레이버 편집기 실행 (Vite dev server)
`npx revideo render`	CLI로 한 번 렌더
`npx revideo render --watch`	파일 변경 감지해서 자동 재렌더
`npx revideo doctor`	FFmpeg/Chromium 환경 진단

▶️ 기본 렌더 — `npx revideo render`

가장 간단한 호출:

npx revideo render

기본값:

진입점: src/project.ts
출력: out/video.mp4
해상도: project.ts의 settings.size 값

🎛️ CLI 옵션

npx revideo render \
  --projectFile=src/project.ts \
  --outFile=out/promo.mp4 \
  --fps=60 \
  --size=1080,1920 \        # 가로,세로
  --variables='{"userName":"김철수","plan":"pro"}'

옵션	설명
`--projectFile <path>`	진입점 파일 (기본 `src/project.ts`)
`--outFile <path>`	출력 mp4 경로 (기본 `out/video.mp4`)
`--fps <n>`	프레임 레이트
`--size <w>,<h>`	해상도 (예: `1280,720`)
`--variables <json>`	`variables` 주입 (JSON 문자열)
`--workerFile <path>`	워커 스크립트 (multi-process 렌더 시)
`--importmap <path>`	importmap 커스텀
`--logLevel <level>`	`info` / `warn` / `error`

--variables는 project.ts의 variables 객체에 깊이 병합된다. CLI에서 부분 덮어쓰기 가능.

👀 watch 모드

npx revideo render --watch

src/ 하위 파일이 변경될 때마다 자동으로 재렌더. Studio보다 가볍고, CI 디버깅이나 짧은 클립 반복 작업에 좋다.

$ npx revideo render --watch
[revideo] watching src/...
[revideo] change detected: src/scenes/example.ts
[revideo] rendering... 0% → 100% (3.2s)
[revideo] out/video.mp4 written (1.4 MB)

🩺 환경 진단 — `revideo doctor`

ffmpeg / chromium / node 버전, GPU 가속 가능 여부 등을 한 번에 점검:

$ npx revideo doctor
[OK]   Node.js v20.10.0 (>= 18 required)
[OK]   ffmpeg 6.1.1 (at /usr/local/bin/ffmpeg)
[OK]   Chromium 119.0.6045.105
[WARN] No hardware acceleration — software encoder only
[OK]   All systems go.

⚠️ ffmpeg not found가 뜨면 FFmpeg Issues 참고. macOS는 brew install ffmpeg, Ubuntu는 sudo apt install ffmpeg.

🧪 Studio vs CLI — 언제 뭘 쓰나

상황	권장 도구
변수 슬라이더로 실시간 미리보기	Studio (`npm start`)
빠른 단발 렌더 + 디버깅	CLI (`npx revideo render`)
Scene 코드 반복 편집	Studio → 최종 확인은 CLI
CI에서 단위 렌더	CLI (스크립트화)
자동화 파이프라인	CLI + `--variables` JSON

📦 일반적인 워크플로우

# 1) Studio로 인터랙티브 편집
npm start

# 2) 최종 결과를 CLI로 한 번 더 검증
npx revideo render --variables='{"userName":"final"}'

# 3) 배포
scp out/video.mp4 user@server:/var/www/

🚀 다음 단계

작업	가이드
서버에 렌더 엔드포인트 만들기	Revideo 렌더링 서비스 배포
렌더 트러블슈팅	Revideo FFmpeg Issues
렌더 속도 최적화	Revideo 성능 & 최적화

🔗 공식 리소스

공식 문서: https://midrender.com/revideo/docs/guide/building-webapps/rendering-endpoint
GitHub: https://github.com/midrender/revideo
예제 모음: https://github.com/redotvideo/examples

상위 문서: ← Revideo 렌더링 출처: Revideo 공식 문서 — Local Development with the CLI 한글화 (2026-07-29) 공급사: Revideo (현 Midrender)

변경 이력

날짜	변경
2026-07-29	초안 작성 — CLI 로컬 개발 워크플로우 + doctor/watch 모드