Communitygithub.com

BintzGavin/helios-skills

自动化将 Helios 合成动画渲染为视频文件的工作流。适用于需要自动化视频制作或导出高质量动画的场景。

helios-skills 是什么?

该技能提供了一套完整的 Helios 合成动画渲染工作流,允许开发者通过命令行或 Node.js 脚本将 HTML 合成动画高效地转换为 MP4 等视频文件。它利用 `@helios-project/renderer` 包,支持自定义时长、帧率、分辨率,并可添加多条音轨和输入属性,非常适合自动化视频生成和批量渲染任务。技能文档覆盖了从快速单命令渲染(使用 `npx`)到可高度定制的脚本渲染,包括错误排查指南。支持基于 Canvas 或 DOM 的动画模式,并提供了音频编解码器配置。适用于 Cursor、Codex、Claude Code 等 AI 编码代理,帮助开发者在无需手动操作视频编辑软件的情况下,快速生成高质量动画视频。

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

在你喜欢的 AI 中提问

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

文档

渲染视频工作流

渲染是按帧捕获合成并将其编码为视频文件(例如 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 并传递其 URLs 代替。

仅当您需要自定义管道(例如输入属性、多条音轨或进度回调)时,才使用下面的脚本。

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. 初始化渲染器
    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(`开始渲染 ${compositionUrl}...`);

    // 3. 执行渲染
    try {
        await renderer.render(compositionUrl, outputPath, {
            onProgress: (p) => {
                const percent = Math.round(p * 100);
                process.stdout.write(`\r进度: ${percent}%`);
            }
        });
        console.log(`\n完成!已保存至 ${outputPath}`);
    } catch (err) {
        console.error('\n渲染失败:', 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.

相关技能