Communitygithub.com

ak:hyperframes

HeyGen HyperFrames CLI をラップし、HTML ファーストでプログラム的に動画を生成します。短尺の縦型・ソーシャル動画、プロダクトローンチクリップ、HTML 構成からレンダリングされるモーショングラフィックスに最適です。React ベースの代替手段として、インストール済みの remotion スキルもご利用いただけます。

ak:hyperframes とは?

このスキルは、HeyGen の HyperFrames CLI をラップして、HTML ファーストでプログラム的に動画を生成するためのドキュメントとラッパーです。短尺の縦型ソーシャル動画(1080×1920、9:16)を HTML/CSS からレンダリングしたり、プロダクトローンチクリップやプロモループ、モーショングラフィックスを HTML 構成で作成するのに適しています。React コンポーネントやタイムラインエディタではなく、HTML マークアップを構成の真実の源泉としたい場合に最適です。利用には Node.js 22 と FFmpeg が必要で、リモートレンダリングには HeyGen API キーがオプションで利用できます。このスキルは `npx` を使って公開 npm パッケージ(バージョン 0.7.99 に固定)を実行するため、外部の HeyGen ソースコードをベンダリングせず、HeyGen エージェントスキルもコピーしていません。標準的なワークフローは `init → HTML編集 → preview → lint → render` のループで、`lint` を `render` の前に必ず実行することで、レンダリング失敗を防ぎます。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ngocsangyem/reporeaper/tree/HEAD/.claude/skills/ak-hyperframes

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

ak:hyperframes は何をしますか?

HeyGen の hyperframes CLI をラップし、HTML ファーストでプログラム的に動画を生成します。このスキルはドキュメントとラッパーのみであり、HeyGen のソースコードをベンダリングしたり、HeyGen のエージェントスキルをコピーしたりしていません。以下のすべてのコマンドは、公開されている npm パッケージを npx で実行し、既知の正常なバージョンに固定されています。

使用するタイミング

  • HTML/CSS からレンダリングされる短尺の縦型ソーシャル動画(1080×1920、9:16)。
  • React コンポーネントやタイムラインエディタではなく、HTML 構成として作成されたプロダクトローンチクリップ、プロモループ、モーショングラフィックス。
  • data-composition-id / data-start タイミング属性を含む HTML マークアップが構成の真実の源泉となるタスク(references/composition-basics.md を参照)。

React ファーストの構成、フレーム精度の補間カーブ、Remotion のオーディオ/キャプションエコシステムには適していません。その代替として、インストール済みの remotion スキル(React ベースのプログラム動画生成)もご利用いただけます。また、純粋な FFmpeg/ImageMagick エンコードタスクにも適していません。その代替として ak-media-processing スキルをご利用ください。

前提条件

  • Node.js 22+
  • PATH に FFmpeg がインストールされていること
  • オプション: リモートレンダリング用の HeyGen クラウド/ラムダ API キー(HEYGEN_API_KEY)。ローカルレンダリングはキーなしで動作します。

レンダリング作業を開始する前に、バンドルされている検証スクリプトを実行してください:

node scripts/verify-prereqs.mjs
# または、機械可読な出力を得るには:
node scripts/verify-prereqs.mjs --json

各プラットフォームのインストール手順と固定バージョン確認の注意事項については、references/env-and-deps.md を参照してください。

固定 CLI バージョン

以下のすべての呼び出しは [email protected] に固定されています。これは 2026-08-07 時点の最新公開バージョンです(npm view hyperframes version で確認)。アップグレード時は、このファイルと references/render-workflow.md の固定バージョンを 1 箇所で更新してください。スクリプトやドキュメント内で、固定されていない npx -y hyperframes ... を実行しないでください。

ワークフロー

標準ループは init → HTML編集 → preview → lint → render です。各ステージの具体的な呼び出しの詳細は references/render-workflow.md にあります。簡略版は以下の通り:

# 1. 新しいコンポジションプロジェクトをスキャフォールド
npx -y [email protected] init my-composition --resolution portrait

# 2. 生成された HTML コンポジションを編集(data-composition-id / data-start / data-width / data-height の契約については composition-basics.md を参照)

# 3. ローカル開発サーバーでプレビュー
npx -y [email protected] preview my-composition

# 4. レンダリング前にコンポジションを lint(不正なタイミング属性をキャッチ)
npx -y [email protected] lint my-composition

# 5. MP4 にレンダリング
npx -y [email protected] render my-composition --output ./assets/videos/my-composition.mp4

render の前に必ず lint を実行してください。lint がクリーンなコンポジションは、lint をスキップして直接レンダリングする場合よりも、レンダリングステップで失敗する頻度が大幅に低くなります。

コンポジション契約

HyperFrames コンポジションは、ルート要素に data-composition-id、data-start、data-width、data-height 属性が注釈されたプレーンな HTML ファイルです。完全な属性リファレンスと縦型 1080×1920 の例については、references/composition-basics.md を参照してください。

参考資料

  • references/heygen-skills.md — このラッパーが再実装せずに参照する 25 の HeyGen エージェントスキル。より深い HyperFrames 固有の専門知識(アニメーション、キーフレーム、キャプション、プロダクトローンチテンプレートなど)が必要な場合は、npx -y [email protected] skills でインストールしてください。
  • references/composition-basics.md — HTML コンポジション属性契約の完全な縦型プリセット例。
  • references/render-workflow.md — init → edit → preview → lint → render フローのすべての固定呼び出しを含む完全版。
  • references/env-and-deps.md — プラットフォームごとの Node/FFmpeg/API キーのセットアップ。

トラブルシューティング

症状対応
command not found: ffmpegnode scripts/verify-prereqs.mjs を実行し、あなたのプラットフォームに正確な修正方法を確認してください。
npx hyperframes が不明なフラグを報告このファイルの固定バージョンが上流より遅れている可能性があります。固定を更新する前に、npx -y [email protected] --help を実行して現在のフラグを確認してください。
render が白または短い MP4 で失敗最初に lint を実行してください。ほとんどのレンダリング失敗は、lint でキャッチされる不正な data-start/data-composition-id 属性が原因です。
リモート/クラウドレンダリングが必要HEYGEN_API_KEY を references/env-and-deps.md に従って設定し、hyperframes cloud render(render フラグではなく、別のトップレベルコマンド)を使用してください。references/render-workflow.md を参照。

関連項目

  • インストール済みの remotion スキル(ak-remotion)— React ベースのプログラム動画生成。構成が HTML マークアップではなく、自然に React コンポーネントツリーになる場合に使用します。
  • ak-html-video スキル — 別の HTML から MP4 へのラッパー(nexu-io/html-video)。独自のテンプレート/Studio ワークフローを持ちます。タスクが HeyGen HyperFrames コンポジションである場合に限り、ak-hyperframes を使用してください。
  • ak-motion-graphics スキル — リポジトリ内のすべての動画/モーションスキルと外部モーションスキルパックをルーティングします。

関連スキル