Communitygithub.com

BintzGavin/helios-skills

用於將 Helios 合成影片渲染成影片檔案的工作流程。當你需要自動化影片製作或匯出高畫質動畫時使用。

helios-skills 是什麼?

這個技能提供一個完整的 Helios 合成影片渲染工作流程,能夠將網頁動畫逐幀捕捉並編碼成 MP4 等影片檔案。它利用 @helios-project/renderer 套件在 Node.js 環境中運作,支援直接使用 CLI 命令快速渲染,也可透過自訂腳本實現進階功能,如輸入屬性、多音軌、進度回呼等。使用者可以設定影片解析度、幀率、持續時間,以及選擇 canvas 或 dom 渲染模式。此技能支援在 Cursor、Claude Code 和 Codex 等 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)的過程。這是使用 @helios-project/renderer 套件在 Node.js 環境中完成的。

快速路徑:一個指令

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 並改傳入其網址。

僅當你需要自訂管道(例如輸入屬性、多個音軌或進度回呼)時,才使用以下腳本。

1. 先決條件

渲染器需要合成影片的網址:

  • 磁碟上的檔案:file:///path/to/composition.html
  • 開發伺服器:npm run dev,例如 http://localhost:3000/composition.html
  • 任何其他可存取的網址

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: "自訂渲染",
            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

疑難排解

「頁面逾時」或「連線被拒絕」

  • 確保執行合成影片的本機伺服器正在執行。
  • 檢查網址是否正確且在一般瀏覽器中可存取。

「黑色輸出」或「空白影片」

  • 確保 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.

相關技能