Communitygithub.com

Helios 렌더링 워크플로우

Helios 컴포지션을 비디오 파일로 렌더링하는 자동화 워크플로우입니다. 애니메이션 제작 자동화나 고품질 비디오 출력이 필요할 때 사용하세요.

Helios 렌더링 워크플로우란 무엇인가요?

이 스킬은 Helios 프로젝트에서 제작한 컴포지션을 비디오 파일(예: MP4)로 렌더링하는 프로세스를 안내합니다. 주로 `@helios-project/renderer` 패키지를 사용하며, 간단한 명령어 한 줄로 시작하거나, 여러 오디오 트랙, 입력 속성, 진행 콜백 등이 필요한 복잡한 파이프라인을 위해 스크립트를 작성할 수도 있습니다. 이는 Claude Code와 같은 AI 코딩 어시스턴트에서 직접 사용할 수 있도록 설계되었으며, Node.js 환경에서 실행됩니다. 사용자는 Helios 컴포지션이 포함된 HTML 파일의 URL만 제공하면 나머지 렌더링 과정을 자동화할 수 있습니다. 디버깅을 위한 트레이싱 기능, 오디오 트랙 추가, 모드 선택(canvas/dom) 등 다양한 고급 옵션을 지원하여 유연한 비디오 제작 워크플로우를 제공합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/BintzGavin/helios-skills/tree/HEAD/skills/workflows/render-video

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

비디오 렌더링 워크플로우

렌더링은 컴포지션을 프레임별로 캡처하여 비디오 파일(예: 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에 있는지 확인하세요.

Individual skills in this repo

This repo contains 9 individual skills — each has its own dedicated page.

BintzGavin/helios-skills

Make a video, MP4, GIF, animation, music video, short film, explainer, chart animation, product demo, logo reveal or social clip from code. Write one HTML page that draws any frame from its time t, render it frame-exact to MP4 with Helios, check stills and contact sheets, and add a soundtrack. Use whenever the user asks for a video or an animation file.

BintzGavin/helios-skills

>- Story-first motion design philosophy for animated video: motion must earn its place; arc (establish, complicate, resolve); show vs tell; shots as units of thought; quiet vs loud motion; Disney principles with restraint; timing heuristics; composition; grammar by medium (product demos, logos, data viz, explainers); technical commitments (deterministic time, scrubbability, refs); cutting discipline; explicit anti-patterns. Use when planning, storyboarding, critiquing, or implementing programmatic or motion-driven video (Helios, Remotion, explainers, loops, UI capture, logo reveals), or when the user asks for motion direction, pacing, or visual-story structure.

BintzGavin/helios-skills

>- End-to-end production plan template for feeling-first cinematic product promos: brief interrogation, 45s beat structure (cold open through brand), hero-element metaphor, storyboard fidelity ladder, visual system (palette, type, camera, texture), motion mix and easing vocabulary, audio and captions, tooling (animatic through HTML or AE), deliverables matrix, accessibility, review milestones, and compromises to accept or refuse. Use when planning, pitching, storyboarding, or producing polished brand films for any SaaS or consumer product—not category-specific; pair with skills/design/animated-video-philosophy for broader motion principles.

BintzGavin/helios-skills

Patterns for using Helios with Framer Motion. Use when you want to use Framer Motion's physics and transitions but need frame-perfect synchronization with Helios.

BintzGavin/helios-skills

Patterns for using Helios with GSAP (GreenSock). Use when integrating GSAP timelines with the Helios timeline for precise scrubbing and rendering.

BintzGavin/helios-skills

End-to-end guided workflow for creating an explainer or walkthrough video. Extracts brand identity from the repo, generates a measured soundtrack, and produces a narrative-driven motion.dev composition rendered via Helios CLI. Use when making how-it-works, feature walkthrough, or educational videos.

BintzGavin/helios-skills

Motion design framework for programmatic video. Defines anti-slideshow architecture, visual layering, physics-based easing, choreography rules, and quality validation. Reference this skill from any guided video skill.

BintzGavin/helios-skills

End-to-end guided workflow for creating a promotional hype video. Extracts brand identity from the repo, generates beat-synced music, and produces a high-energy motion.dev composition rendered via Helios CLI. Use when making brand-aligned promo or hype videos.

BintzGavin/helios-skills

End-to-end guided workflow for creating a social proof or testimonial video. Extracts brand identity from the repo, generates a warm soundtrack, and produces a trust-building motion.dev composition rendered via Helios CLI. Use when making customer testimonial, review highlight, or social proof videos.

관련 스킬