비디오 렌더링 워크플로우
렌더링은 컴포지션을 프레임별로 캡처하여 비디오 파일(예: MP4)로 인코딩하는 과정입니다. 이 작업은 Node.js 환경에서 @helios-project/renderer 패키지를 사용하여 수행됩니다.
빠른 경로: 한 줄 명령어
npx -y @helios-project/cli@latest render composition.html -o output.mp4
- 지속 시간, FPS 및 크기는 컴포지션의
window.helios에서 가져옵니다. 직접 설정하려면--duration,--fps,--width및--height를 전달하세요. window.renderAt(t)로 자체 그리는 페이지에는--duration이 필요합니다.--audio track.mp3는 사운드트랙을 추가합니다.- 일반 HTML 파일은 디스크에서 직접 렌더링됩니다. 번들러가 컴포지션을 빌드해야 하는 경우
npm run dev를 실행하고 대신 해당 URL을 전달하세요.
입력 속성, 여러 오디오 트랙 또는 진행 콜백과 같은 사용자 정의 파이프라인이 필요한 경우에만 아래 스크립트를 사용하세요.
1. 전제 조건
렌더러에는 컴포지션의 URL이 필요합니다:
- 디스크의 파일:
file:///path/to/composition.html - 개발 서버:
npm run dev, 예:http://localhost:3000/composition.html - 접근 가능한 다른 URL
2. 렌더 스크립트 생성
render.js(또는 ts-node를 사용하는 경우 render.ts) 파일을 만드세요.
import { Renderer } from '@helios-project/renderer';
import path from 'path';
async function main() {
// 1. 설정
const compositionUrl = 'http://localhost:3000/composition.html';
const outputPath = path.resolve('output.mp4');
// 2. Renderer 초기화
const renderer = new Renderer({
width: 1920,
height: 1080,
fps: 30,
durationInSeconds: 10,
// frameCount: 300, // 선택 사항: durationInSeconds를 정확한 프레임 수로 재정의
mode: 'canvas', // 애니메이션이 CSS/HTML 요소를 사용하는 경우 'dom' 사용
// 오디오 설정
audioTracks: [
{ path: 'background.mp3', volume: 0.5 },
{ path: 'voiceover.wav', offset: 2 }
],
audioCodec: 'aac',
// 입력 속성 (동적 콘텐츠)
inputProps: {
title: "Custom Render",
color: "#00ff00"
}
});
console.log(`Starting render of ${compositionUrl}...`);
// 3. 렌더링 실행
try {
await renderer.render(compositionUrl, outputPath, {
onProgress: (p) => {
const percent = Math.round(p * 100);
process.stdout.write(`\rProgress: ${percent}%`);
}
});
console.log(`\nDone! Saved to ${outputPath}`);
} catch (err) {
console.error('\nRender failed:', err);
process.exit(1);
}
}
main();
3. 렌더 실행
스크립트를 실행합니다.
# ts-node를 사용하는 경우
npx ts-node render.ts
# node를 사용하는 경우 (컴파일된 js)
node render.js
문제 해결
"페이지 시간 초과" 또는 "연결 거부"
- 컴포지션을 호스팅하는 로컬 서버가 실행 중인지 확인하세요.
- URL이 올바르고 일반 브라우저에서 접근 가능한지 확인하세요.
"검은색 출력" 또는 "빈 비디오"
window.helios가 노출되었는지(또는 페이지가window.renderAt(t)를 정의했는지) 확인하세요.mode: 'canvas'를 사용하는 경우<canvas>요소에 그리고 있는지 확인하세요.mode: 'dom'을 사용하는 경우 요소가 표시되는지 확인하세요.
"렌더링이 중단됨"
- 컴포지션에 브라우저 콘솔에 오류가 있는지 확인하세요.
- 디버깅을 위해 트레이싱을 활성화합니다:
await renderer.render(url, out, { tracePath: 'trace.zip' });
오디오 문제
- 오디오 파일 경로가 스크립트가 실행되는 위치를 기준으로 올바른지 확인하세요.
mode: 'dom'을 사용하고 암시적 오디오(예:<audio>태그)에 의존하는 경우 해당 요소가 DOM에 있는지 확인하세요.