Communitygithub.com

BintzGavin/helios-skills

从代码生成视频、MP4、GIF、动画、音乐视频、短片、解说、图表动画、产品演示、Logo 揭示或社交剪辑。编写一个 HTML 页面,该页面根据时间 t 绘制任何帧,然后使用 Helios 精确渲染每一帧并输出 MP4,检查静态帧和联系表,还可添加配乐。当用户要求生成视频或动画文件时使用。

helios-skills 是什么?

这是一个名为 Helios 的视频生成技能,允许开发者通过编写一个纯 HTML 页面来创建精确到帧的视频、动画和 GIF。其核心思想是定义一个单一的 JavaScript 函数 `window.renderAt(t)`,该函数根据时间参数 `t`(秒)绘制视频的每一帧。Helios 的渲染器会在无头 Chrome 中加载此页面,对每一帧调用 `renderAt`,捕获帧并编码为 MP4,无需打包工具或框架。该技能支持任意帧大小、帧率、配乐(同步或非同步),并提供了 `verify` 命令来检查页面是否真的是 `t` 的纯函数(避免使用计数器或未种子化的随机数)。此外,它还支持导出静态 PNG、联系表(contact sheet)以及通过区域裁剪进行调试,非常适合制作产品演示、数据可视化动画、音乐可视化或 Logo 动画。Helios 在 Windows、macOS 和 Linux 上均可运行,通过 `npx` 命令即可快速使用,无需安装全局依赖。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/BintzGavin/helios-skills/tree/HEAD/plugins/helios/skills/make-video

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

使用 Helios 制作视频

Helios 视频是一个包含单一函数 window.renderAt(t) 的 HTML 页面。该函数在 t 秒时绘制相应帧。Helios 渲染器会在无头 Chrome 中加载页面,每帧调用一次 renderAt(t),捕获每一帧并编码为 MP4。无需打包工具、框架或编写捕获脚本。

1. 编写页面

每一帧必须是 t 的纯函数。渲染器可能以任意顺序请求帧,并且每次渲染同一帧的结果必须完全相同。

  • 一切从 t 派生: 位置、透明度、显示哪个场景。绝不要使用计数器、x += speed、逐帧步进的物理模拟或 setTimeout/setInterval。
  • 随机性必须接入种子。 在 renderAt 内部使用下面的 rand(seed),而不是裸 Math.random()。
  • 在第一帧之前加载资源。 为字体和图片维护一个 ready promise,使 renderAt 为 async 并 await ready。渲染器会等待 renderAt 返回的任何 promise。
  • 页面尺寸与视频一致。 画布尺寸等于视频尺寸,并设置 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);         // 在 [start, start+dur] 区间内从 0 → 1
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–3s):标题淡入升起。
  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 <s>视频长度(秒)。支持小数。对于 renderAt 页面是必需的。
--width 1080 --height 1920帧尺寸;默认为 1920×1080。需与你的画布匹配。竖屏 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 并检查:

  • 文字清晰可读且在画面内
  • 过渡确实发生
  • 没有空白或黑色帧
  • 节奏符合要求

修复页面,再次检查,然后重新渲染。

4. 音乐和音效

--audio 会混入一个音频文件。要使画面与音乐同步,可使用以下方法之一:

  • 已知 BPM: 第 k 个节拍落在 k * 60 / bpm 秒。根据 t 以此网格驱动脉冲。
  • 未知节奏: 在页面中分析音频。解码一次,预先计算响度包络,然后在 renderAt 中根据 t 读取该包络。参见 references/music.md。

出现问题时的对策

症状解决方法
"How long should the video be? Pass --duration"添加 --duration <seconds>。
window.renderAt(2.5) threw: …你的页面在此时出错。消息中包含你的堆栈跟踪。
首次渲染时暂停下载 Chromium这是预期的,且只会发生一次。不要自行运行 npx playwright install:它会获取错误的 Playwright 版本的构建。
"The page defines no window.helios, window.renderAt(t) …"你的脚本从未定义 renderAt。检查页面是否有加载错误,例如语法错误或导入失败。
两次渲染之间帧不同,或 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.

相关技能