superyhee/hypr-video-skills

CLI를 통한 비디오 생성

빠른 참조

# 설정 파일 작성 → JSON 생성 → 렌더링
node scripts/gen_canvas.mjs /tmp/video-<name>.mjs /tmp/video-<name>.json
npx hypr-video-cli /tmp/video-<name>.json -o ./output/<name>.mp4

워크플로우

- [ ] 1단계: 참조 문서 읽기 및 장면 계획
- [ ] 2단계: 설정 파일 작성 및 JSON 생성
- [ ] 3단계: 렌더링 및 확인

1단계 — 참조 문서 읽기 및 장면 계획

1a. 다음 참조 문서를 읽으세요(항상 필요):

• gen-canvas.md — 설정 사양: theme() (24개 테마), 11개 역할 헬퍼, autoTracks(), 인라인 animIn/animOut/kf, SVG 헬퍼, buildCanvas. 주의사항은 ⚠️ 표시와 함께 제공됩니다.

1b. 장면 계획: 비디오 유형 식별, 장면 이름/지속 시간 목록 작성, 장면별 최적의 SVG 헬퍼 선택, 최적의 요소와 이모지 선택.

1c. 계획에 따라 추가 문서 읽기:

상황	참조 문서
SVG 헬퍼를 사용하는 경우 (거의 항상)	svg-helpers.md — 65개 모든 헬퍼의 매개변수
폰트 선택 시	font-assets.md — 18개 번들 폰트 및 조합
이모지/유니코드 장식 추가 시	icons.md

2단계 — 설정 파일 작성 및 JSON 생성

2a. 설정 .mjs 파일을 작성하세요. 설정 파일과 JSON은 /tmp/에 저장하세요 — 절대 examples/에 쓰지 마세요.

export default function build(h) {
  const {
    makeShape, makeEffect, buildCanvas, theme, autoTracks,
    svgVignette, svgDotGrid, svgGradientOrb, svgParticles,
    svgCheckMark, svgNumberCounter, // ...필요한 SVG 헬퍼
  } = h;

  const t = theme("cyberpunk");  // 24개 테마 — 색상 + 역할 헬퍼 + 폰트
  const MAX = 25000;

  // ── 전역 레이어 ──
  const g_dot = svgDotGrid("g_dot", { start: 0, end: MAX, opacity: 0.04, color: t.ACCENT });
  const g_vig = svgVignette("g_vig", { start: 0, end: MAX, opacity: 0.6 });

  // ── 장면 1: 히어로 (0–7초) ──
  const s1_orb = svgGradientOrb("s1_orb", {
    x: 360, y: 60, w: 1200, h: 960, start: 0, end: 7500, opacity: 0.10, color: t.ACCENT,
  });
  const s1_title = t.hero("s1_title", "제품 이름", {
    x: 160, y: 340, start: 0, end: 7000,
    animIn: ["blurIn", 1200], animOut: ["blurOut", 700],
    kf: { scale: { dur: 7000, amp: 0.02 } },
  });
  const s1_div = makeShape("s1_div", "rect", t.ACCENT, {
    x: 760, y: 510, w: 400, h: 3, start: 500, end: 6500,
    animIn: ["expandIn", 500], animOut: ["fadeOut", 300],
  });
  const s1_sub = t.subtitle("s1_sub", "여기에 태그라인 입력", {
    x: 260, y: 540, start: 700, end: 6500,
    animIn: ["fadeIn", 800], animOut: ["fadeOut", 500],
  });

  // ── 장면 2: 특징 (6.5–16초) ──
  // ... 더 많은 장면이 동일한 패턴으로 이어짐

  const elements = [g_dot, g_vig, s1_orb, s1_title, s1_div, s1_sub /* ... */];

  return buildCanvas({
    bg: t.BG, maxTime: MAX,
    // t.fonts는 객체 { Montserrat: {...}, "Fira Code": {...}, ... }입니다 — 배열이 아닙니다
    // 추가 폰트(예: CJK)를 추가하려면 객체 스프레드를 사용하세요:
    fontAssets: {
      ...t.fonts,
      "Noto Sans SC": { url: "skill/assets/fonts/NotoSansSC-Variable.ttf", fileType: "ttf" },
    },
    elements, tracks: autoTracks(elements),
    fps: 30, quality: "medium",
  });
}

node scripts/gen_canvas.mjs /tmp/video-<name>.mjs /tmp/video-<name>.json

2b. 렌더링 전에 다음을 확인하세요:

1. 모든 텍스트는 역할 헬퍼(t.hero … t.eyebrow)를 사용합니다 — 사용자 정의 폰트/크기/색상(예: 코드 블록, Noto Sans SC를 사용한 CJK)이 필요한 경우에만 makeText를 직접 사용하세요.
2. 모든 보이는 요소에는 animIn + animOut이 있으며, 요소 간 간격은 300–500ms로 설정하세요.
3. SVG 배경 불투명도 ≤ 0.15, 장면당 2–4개의 헬퍼, 전역 레이어는 0–MAX 범위를 차지합니다.
4. maxTime >= 마지막 요소의 end

3단계 — 렌더링 및 확인

npx hypr-video-cli /tmp/video-<name>.json -o ./output/<name>.mp4

CLI 플래그: --fps 24|30|60, --quality low|medium|high|very_high, --format mp4|mov|mp3, --width N, --height N, -q (조용히 실행).

렌더링 실패 시 → gen-canvas.md의 ⚠️ 주의사항 확인

중요 규칙

1. maxTime >= 가장 큰 요소의 end — 너무 작으면 요소가 잘립니다.
2. 설정 파일은 /tmp/에 저장 — 절대 examples/에 쓰지 마세요.
3. 항상 최신 API 사용 — theme() + 역할 헬퍼 + 인라인 animIn/animOut/kf + autoTracks().
4. 장면 구조 — 요소 ID 앞에 장면별로 s1_/s2_… 접두사 사용, 주석 블록 // ── 장면 N: 제목 (Xs–Ys초) ── 사용
5. 전환 효과 — 같은 트랙에 인접한 요소가 필요합니다 (효과 기반 플래시/글리치 컷 선호)
6. backgroundColor는 bg: t.BG로 설정 — 전체 화면 배경 모양을 사용하지 마세요.
7. gen_canvas.mjs 경로 — 스킬 루트에서 실행: node scripts/gen_canvas.mjs (skill/scripts/ 아님)
8. t.fonts는 객체, 배열이 아님 — { ...t.fonts, "Extra Font": { url: "...", fileType: "ttf" } }로 폰트를 추가하세요. 절대 [...t.fonts] (배열 스프레드)를 사용하지 마세요.