Hypr Video CLI

Video Generation via CLI

Quick Reference

# Write config → generate JSON → render
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

Workflow

- [ ] Step 1: Read references & plan scenes
- [ ] Step 2: Build config & generate JSON
- [ ] Step 3: Render & verify

Step 1 — Read references & plan scenes

1a. Read these references (always required):

• gen-canvas.md — config spec: theme() (24 themes), 11 role helpers, autoTracks(), inline animIn/animOut/kf, SVG helpers, buildCanvas. Pitfalls are inline with ⚠️ markers.

1b. Plan scenes: identify video type, list scene names/durations, pick best SVG helpers per scene, pick best elements and emoji.

1c. Read extras based on the plan:

Step 2 — Build config & generate JSON

2a. Write a config .mjs file. Config and JSON go in /tmp/ — never write to examples/.

export default function build(h) {
  const {
    makeShape, makeEffect, buildCanvas, theme, autoTracks,
    svgVignette, svgDotGrid, svgGradientOrb, svgParticles,
    svgCheckMark, svgNumberCounter, // ...SVG helpers as needed
  } = h;

  const t = theme("cyberpunk");  // 24 themes — colors + role helpers + fonts
  const MAX = 25000;

  // ── Global layers ──
  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 });

  // ── Scene 1: Hero (0–7s) ──
  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", "Product Name", {
    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", "Tagline goes here", {
    x: 260, y: 540, start: 700, end: 6500,
    animIn: ["fadeIn", 800], animOut: ["fadeOut", 500],
  });

  // ── Scene 2: Features (6.5–16s) ──
  // ... more scenes follow the same pattern

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

  return buildCanvas({
    bg: t.BG, maxTime: MAX,
    // t.fonts is an OBJECT { Montserrat: {...}, "Fira Code": {...}, ... } — NOT an array
    // To add extra fonts (e.g. CJK), use object spread:
    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. Before rendering, verify:

1. All text uses role helpers (t.hero … t.eyebrow) — use raw makeText only for custom font/size/color (e.g. code blocks, CJK with Noto Sans SC)
2. Every visible element has animIn + animOut; stagger 300–500ms between elements
3. SVG bg opacity ≤ 0.15; 2–4 helpers per scene; global layers span 0–MAX
4. maxTime >= last element's end

Step 3 — Render & verify

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

CLI flags: --fps 24|30|60, --quality low|medium|high|very_high, --format mp4|mov|mp3, --width N, --height N, -q (quiet).

If render fails → check ⚠️ pitfalls in gen-canvas.md

Critical Rules

1. maxTime >= largest element end — too small = elements cut off
2. Config files go in /tmp/ — never write to examples/
3. Always use modern API — theme() + role helpers + inline animIn/animOut/kf + autoTracks().
4. Scene structure — prefix element IDs with s1_/s2_… per scene; use comment blocks // ── Scene N: Title (Xs–Ys) ──
5. Transitions require adjacent elements on same track (prefer effect-based flash/glitch cuts)
6. Use backgroundColor via bg: t.BG — not a full-screen background shape
7. gen_canvas.mjs path — run from skill root: node scripts/gen_canvas.mjs (NOT skill/scripts/)
8. t.fonts is an object, not an array — use { ...t.fonts, "Extra Font": { url: "...", fileType: "ttf" } } to add fonts. Never use [...t.fonts] (array spread)