Communitygithub.com

BintzGavin/helios-skills

코드로 비디오, MP4, GIF, 애니메이션, 뮤직비디오, 단편 영화, 설명 영상, 차트 애니메이션, 제품 데모, 로고 리빌 또는 소셜 클립을 만듭니다. 시간 t에 따라 프레임을 그리는 HTML 페이지 하나를 작성하고, Helios로 프레임 단위로 MP4로 렌더링하며, 스틸 이미지와 콘택트 시트를 확인하고, 사운드트랙을 추가합니다. 사용자가 비디오 또는 애니메이션 파일을 요청할 때마다 사용하세요.

helios-skills란 무엇인가요?

이 스킬은 사용자가 단일 HTML 페이지와 `window.renderAt(t)` 함수 하나로 비디오, GIF, 애니메이션을 만들 수 있게 해주는 Helios CLI 도구를 감싸고 있습니다. 핵심 원리는 비디오의 모든 프레임을 시간 `t`에 대한 순수 함수로 만드는 것입니다. Helios 렌더러는 헤드리스 Chrome에서 페이지를 로드하고, 프레임당 한 번씩 `renderAt(t)`을 호출하여 각 프레임을 캡처하고 MP4로 인코딩합니다. 이 접근 방식은 프레임 정확성을 보장하며, 번들러나 프레임워크가 필요 없습니다. 이 스킬은 비디오 페이지 작성 방법, 시드 기반 랜덤성 사용 방법, `--duration` 및 `--audio`와 같은 플래그로 렌더링하는 방법, 스틸 이미지와 콘택트 시트를 사용하여 프레임을 검증하는 방법, 오디오와 시각적 요소를 동기화하는 방법을 다룹니다. Claude Code, Cursor, Codex 등 AI 코딩 도구와 함께 사용하도록 설계되어 복잡한 비디오 제작 워크플로를 간소화합니다.

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

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

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

문서

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.

Individual skills in this repo

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

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.

BintzGavin/helios-skills

Workflow for rendering a Helios composition to a video file. Use when you need to automate video production or export a high-quality animation.

관련 스킬