Helios로 비디오 만들기
Helios 비디오는 하나의 HTML 페이지와 하나의 함수 window.renderAt(t)로 구성됩니다. 이 함수는 t초에 해당하는 프레임을 그립니다. Helios 렌더러는 헤드리스 Chrome에서 페이지를 로드하고, 프레임당 한 번씩 renderAt(t)을 호출하며, 각 프레임을 캡처하고 MP4로 인코딩합니다. 번들러, 프레임워크 또는 별도의 캡처 스크립트를 작성할 필요가 없습니다.
1. 페이지 작성
모든 프레임은 t에 대한 순수 함수여야 합니다. 렌더러는 어떤 순서로든 프레임을 요청할 수 있으며, 동일한 프레임은 매번 동일하게 렌더링됩니다.
- 모든 것을
t로부터 도출하세요: 위치, 투명도, 어떤 장면이 표시되는지 등. 카운터,x += 속도, 프레임 단위로 진행되는 물리 엔진,setTimeout/setInterval을 절대 사용하지 마세요. - 무작위성은 시드(seed)를 기반으로 해야 합니다.
renderAt내부에서 일반Math.random()대신 아래의rand(seed)를 사용하세요. - 첫 번째 프레임 전에 에셋을 로드하세요. 폰트와 이미지에 대한
ready프라미스를 유지하고,renderAt을 비동기(async)로 만들고await ready를 사용하세요. 렌더러는renderAt이 반환하는 모든 프라미스를 기다립니다. - 페이지 크기를 비디오 크기에 맞추세요. 비디오 크기와 동일한 크기의 캔버스에
html,body{margin:0;overflow:hidden}스타일을 사용합니다.
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<style>html,body{margin:0;background:#0b0b10;overflow:hidden}</style>
</head>
<body>
<canvas id="c" width="1920" height="1080"></canvas>
<script>
const W = 1920, H = 1080;
const ctx = document.getElementById('c').getContext('2d');
const clamp = (x, a = 0, b = 1) => Math.min(b, Math.max(a, x));
const ease = (x) => 1 - Math.pow(1 - clamp(x), 3); // easeOutCubic
const span = (t, start, dur) => clamp((t - start) / dur); // 0→1, [start, start+dur] 범위
const rand = (seed) => { const x = Math.sin(seed * 12.9898) * 43758.5453; return x - Math.floor(x); };
const ready = document.fonts.ready; // 로드하는 이미지도 여기에 추가
window.renderAt = async (t) => {
await ready;
ctx.fillStyle = '#0b0b10';
ctx.fillRect(0, 0, W, H);
// 장면 1 (0–3초): 제목이 위로 올라오며 나타납니다.
const p = ease(span(t, 0.2, 1.2));
ctx.globalAlpha = p;
ctx.fillStyle = '#f5b700';
ctx.font = '800 140px system-ui, sans-serif';
ctx.textAlign = 'center';
ctx.fillText('Hello, video', W / 2, H / 2 + 60 * (1 - p));
ctx.globalAlpha = 1;
// 입자: 입자당 시드 기반 위치, t로 애니메이션.
for (let i = 0; i < 80; i++) {
const x = (rand(i) * W + t * 60 * (0.5 + rand(i + 99))) % W;
const y = rand(i + 7) * H;
ctx.fillStyle = `rgba(255,255,255,${0.15 + 0.35 * rand(i + 3)})`;
ctx.fillRect(x, y, 3, 3);
}
};
</script>
</body>
</html>
DOM, CSS, SVG 및 WebGL 페이지도 동일하게 작동합니다. renderAt 내부에서 t로 스타일을 설정하거나, CSS 애니메이션 및 GSAP/motion 타임라인이 실행되도록 놔두세요. 렌더러가 각 프레임의 시간에 맞춰 이를 탐색합니다. 자세한 내용은 references/pages.md를 참조하세요.
2. 렌더링
npx -y @helios-project/cli@latest render video.html -o video.mp4 --duration 12
| 플래그 | 사용법 |
|---|---|
--duration <초> | 비디오 길이(초). 소수점 사용 가능. renderAt 페이지에는 필수입니다. |
--width 1080 --height 1920 | 프레임 크기; 기본값은 1920x1080입니다. 캔버스 크기와 일치시키세요. 세로 9:16은 1080x1920입니다. |
--fps <n> | 프레임 속도; 기본값은 30입니다. |
--audio song.mp3 | 사운드트랙, 비디오 길이에 맞춰 잘림. |
--mode canvas | 페이지가 하나의 전체 화면 <canvas>로만 구성된 경우 더 빠릅니다. 기본값인 dom은 페이지가 보이는 그대로 캡처합니다. |
--preset medium | 최종 파일용. 동일한 품질에서 파일 크기가 몇 배 작아지며 인코딩 시간이 더 오래 걸립니다. 기본값인 ultrafast는 초안 작업에 빠릅니다. |
렌더링은 프레임 정확합니다. 프레임 n은 정확히 renderAt(n / fps)이며, 드롭되거나 중복된 프레임이 없고 시스템 속도에 영향을 받지 않습니다.
GIF의 경우, MP4를 렌더링한 후 변환하세요. references/pages.md를 참조하세요.
3. 완료되었다고 말하기 전에 프레임을 확인하세요
확인하지 않은 비디오를 전달하지 마세요. 페이지 자체에서 스틸 이미지와 콘택트 시트를 렌더링하세요. 빠르고 인코딩이 필요 없습니다:
npx -y @helios-project/cli@latest still video.html --at 0.5,3,7.25 # 전체 크기 PNG
npx -y @helios-project/cli@latest sheet video.html --every 1 --duration 12 # 라벨이 있는 그리드 한 장
npx -y @helios-project/cli@latest sheet video.html --strip 2:3 --fps 30 # 2~3초 구간의 모든 프레임
npx -y @helios-project/cli@latest sheet video.html --at 4 --crop 600,300,720,480 # 특정 영역 확대
긴 렌더링 전에 페이지가 정말 t의 함수인지 확인하세요:
npx -y @helios-project/cli@latest verify video.html --duration 12 # 실패 시 종료 코드 1을 반환하며 이력을 의존하는 프레임 이름을 출력
이미지 뷰어 도구로 PNG를 열고 다음을 확인하세요:
- 텍스트를 읽을 수 있고 프레임 내에 있는지
- 전환이 실제로 일어나는지
- 비어 있거나 검은 프레임이 없는지
- 페이싱(pacing)이 요구사항과 일치하는지
페이지를 수정하고 다시 확인한 후 다시 렌더링하세요.
4. 음악 및 사운드
--audio는 오디오 파일을 먹싱합니다. 시각적 요소를 음악과 동기화하려면 다음 중 하나를 사용하세요:
- 알려진 BPM: 비트
k는k * 60 / bpm초에 발생합니다.t에 대해 해당 그리드에 맞춰 펄스를 구동하세요. - 알 수 없는 템포: 페이지 내에서 오디오를 분석하세요. 오디오를 한 번 디코딩하고 사전에 음량(loudness) 엔벨로프를 계산한 다음,
renderAt에서t에 해당하는 엔벨로프 값을 읽습니다. references/music.md를 참조하세요.
문제가 있을 때
| 증상 | 해결 방법 |
|---|---|
| "비디오 길이가 얼마인가요? --duration을 전달하세요" | --duration <초>를 추가하세요. |
window.renderAt(2.5) threw: … | 해당 시간에 페이지에서 오류가 발생했습니다. 메시지에 스택 추적이 포함됩니다. |
| 첫 번째 렌더링 시 Chromium을 다운로드하며 일시 중지됨 | 예상된 동작이며, 한 번만 발생합니다. 직접 npx playwright install을 실행하지 마세요. 잘못된 Playwright 버전을 가져옵니다. |
| "페이지가 window.helios, window.renderAt(t)를 정의하지 않습니다..." | 스크립트가 renderAt을 정의하지 않았습니다. 구문 오류나 실패한 import와 같은 로드 오류가 있는지 페이지를 확인하세요. |
두 렌더링 간 프레임이 다르거나 verify가 실패함 | t의 함수가 아닌 요소가 있습니다: 시드되지 않은 Math.random(), 카운터 또는 타이머. |
| 빈 WebGL 프레임 | 한 번만 로드할 때가 아니라 renderAt(또는 rAF 루프) 내에서 그리세요. |
더 큰 프로젝트(React/Vue 컴포넌트, 스튜디오 편집, 분산 클라우드 렌더링)는 Helios 패키지를 직접 사용하세요: https://github.com/BintzGavin/helios.