Remotion CLI
도구는 @remotion/cli의 remotion입니다. 모든 명령어는 npx remotion <command>를 통해 실행되며, 각 명령어는 먼저 프로젝트를 번들링하므로 타입 오류나 잘못된 임포트가 렌더 실패가 아닌 번들링 실패로 드러납니다.
npx remotion --help 및 npx remotion <command> --help가 플래그에 대한 권위 있는 정보입니다. 플래그는 릴리스 간에 변경되므로, 이 목록이나 다른 목록을 신뢰하지 말고 도움말 출력을 읽으십시오. 아래 내용은 플래그 참조가 아닌 개발 루프와 실패 모드입니다.
개발 루프
| 단계 | 명령어 | 이유 |
|---|---|---|
| 스캐폴드 | npx create-video@latest --blank | 일치하는 package.json, remotion.config.ts, tsconfig를 생성합니다. |
| 타입 검사 | npx tsc --noEmit | 가장 저렴한 게이트; 렌더 전에 스키마/속성 드리프트를 잡습니다. |
| 목록 조회 | npx remotion compositions | 렌더링하려는 id가 실제로 존재하는지 확인합니다. |
| 프레임 프로브 | npx remotion still <id> out/probe.png --frame=<n> | 분이 아닌 초 단위; 반복 작업의 핵심입니다. |
| 검토 | npx remotion studio | 사용자에게 전달; 사용자가 직접 스크러빙하고 속성을 편집합니다. |
| 렌더 | npx remotion render <id> out/video.mp4 | 사용자 승인 후에만 진행합니다. |
| 원격 전송 | npx remotion bundle → npx remotion lambda render <url> <id> | 분산 렌더; 배포된 AWS 인프라가 필요합니다. |
렌더 전에 스틸 프레브
45초 1080p 컴포지션의 전체 렌더는 몇 분이 소요됩니다. 스틸은 몇 초면 되고 대부분의 질문에 답을 줍니다: 텍스트가 프레임 안에 있는지, 자산이 로드되었는지, 색상이 올바른지. 각 씬의 중간 지점을 프로브하고, 모든 이미지를 확인한 후에만 렌더링하십시오.
npx remotion still launch out/s1.png --frame=45
npx remotion still launch out/s2.png --frame=180
번들 통과만으로 컴포지션이 작동한다고 보고하지 마십시오. 픽셀을 확인하십시오.
스튜디오는 검토 화면이지 디버거가 아닙니다.
npx remotion studio는 타임라인, Zod 스키마로 구동되는 속성 편집기, 프레임 정확한 스크러빙을 제공합니다. 사용자 승인을 위해 전달하십시오. 본인 확인을 위해서는 still 프로브를 선호하십시오: 스크립트 가능하고, 사용자에게 무엇이 보이는지 설명하도록 요청하지 않고 출력을 확인할 수 있습니다.
속성 전달
--props는 JSON 문자열 또는 JSON 파일 경로를 받아 defaultProps를 재정의합니다:
npx remotion render launch out/video.mp4 --props='{"productName":"Acme"}'
컴포지션의 Zod 스키마에 실패하는 속성은 렌더를 크게 실패시킵니다. 이것이 스키마를 선언하는 이유이므로, 정확하게 유지하십시오.
배치 렌더링
별도의 배치 하위 명령어는 없습니다. 셸에서 id 또는 속성 페이로드를 반복하십시오:
for id in $(npx remotion compositions --quiet); do
npx remotion render "$id" "out/$id.mp4"
done
하나의 컴포지션을 데이터 세트에 대해 여러 번 렌더링하는 경우 Node 스크립트에서 @remotion/renderer의 renderMedia()를 사용하는 것이 좋습니다: 렌더당 한 번이 아닌 한 번만 번들링하므로 벽시계 시간이 크게 단축됩니다.
렌더 성능
--concurrency=<n>은 병렬 워커를 설정합니다. 기본값은 CPU 코어의 절반(최대 8)입니다. 최대값은 코어 수이며, 더 많이 요청하면 클램프가 아닌 오류가 발생합니다. 메모리가 부족한 시스템에서는 이를 낮추면 렌더러 버그처럼 보이는 충돌을 해결할 수 있습니다.--jpeg(기본 PNG 프레임 형식 대신)는 투명도를 유지할 필요가 없는 컴포지션에서 큰 속도 향상을 제공합니다.npx remotion benchmark는 실제 렌더를 측정하므로, 추측 대신 이를 사용하여 동시성 또는 코덱 변경을 정당화하십시오.npx remotion gpu는 브라우저가 실제로 가속할 항목을 보고합니다. 느린 렌더의 원인을 셰이더나 무거운 필터 탓으로 돌리기 전에 확인할 가치가 있습니다.
실패 진단
| 증상 | 예상 원인 |
|---|---|
| 번들링 실패 | 타입 오류 또는 잘못된 임포트. 동일한 오류의 읽기 쉬운 버전을 보려면 npx tsc --noEmit을 실행하십시오. |
| "id가 …인 컴포지션이 없습니다" | Root.tsx의 id가 전달한 것과 다릅니다. npx remotion compositions가 이를 해결합니다. |
| 렌더가 멈춘 후 타임아웃 | 일치하는 continueRender()가 없는 delayRender(). 모든 지연 핸들은 해제되어야 합니다. |
| 모든 프레임이 프레임 0처럼 보입니다 | CSS 애니메이션/전환 또는 requestAnimationFrame. 렌더러는 브라우저 시계를 진행시키지 않습니다. |
| 애니메이션이 프레임 간에 깜박이거나 깜박입니다 | 시드되지 않은 Math.random(). 대신 random(seed)를 사용하십시오. |
| 모션은 앞으로 스크러빙할 때 작동하지만 점프 시 깨집니다 | 상태 기반 애니메이션. 대신 useCurrentFrame()에서 파생하십시오. |
| Lambda 또는 번들 렌더에서만 자산 404 발생 | staticFile() 대신 하드코딩된 경로. |
| 이해할 수 없는 버전 오류 | 일치하지 않는 Remotion 패키지. npx remotion versions가 불일치를 보고합니다. |
| 렌더 중간에 메모리 부족 | 시스템에 비해 동시성이 너무 높습니다. --concurrency를 낮추십시오. |
실패를 보고할 때는 실제 오류 출력을 표시하십시오. 스택 트레이스를 의역하지 마십시오.
더 이상 사용되지 않는 HyperFrames CLI 기능이 이동한 위치
이전 hyperframes CLI는 Remotion CLI에는 없는 제작, 미디어 및 QA 명령어를 번들링했습니다. 아래는 Remotion 명령어가 아니므로 실행하려고 시도하지 마십시오:
| 더 이상 사용되지 않는 명령어 | 현재 기능이 있는 위치 |
|---|---|
init | npx create-video@latest --blank한 후, /hyperframes-core → references/project-structure.md |
lint, check, layout, validate | npx tsc --noEmit 및 still 프로브. 이러한 게이트가 시행했던 data-* 계약은 사라졌습니다. |
snapshot, compare, grade-compare | 선택한 프레임에서 npx remotion still; 자체 도구로 PNG를 비교하십시오. |
preview, play, present | npx remotion studio |
add, catalog | /hyperframes-registry |
capture | /product-launch-video (사이트 캡처) 및 /media-use |
tts, transcribe, remove-background | /media-use |
beats, keyframes | /hyperframes-creative (비트 계획), /hyperframes-keyframes |
cloud, publish | npx remotion bundle + remotion lambda / remotion cloudrun, 또는 자체 호스팅 |
skills, docs, upgrade, doctor | 이 스킬들은 이 저장소에 포함되어 있습니다; npx remotion upgrade 및 npx remotion versions |
워크플로우 스킬이나 참조 파일에서 여전히 npx hyperframes <anything>을 실행하도록 지시한다면, 해당 지침은 오래된 것입니다. 위 테이블의 Remotion 등가물을 수행하고, 요약에 오래된 포인터를 발견했으니 수정될 수 있다고 말하십시오.